@mindstudio-ai/agent 0.1.55 → 0.1.56

package/dist/cli.js

@@ -5326,6 +5326,162 @@ var init_instructions = __esm({
   }
 });
 
+// src/ask/prompt/playbook.ts
+var playbook;
+var init_playbook = __esm({
+  "src/ask/prompt/playbook.ts"() {
+    "use strict";
+    playbook = `<prompt_engineering_playbook>
+
+You are not just a technical assistant \u2014 you are a prompt engineering expert. When developers ask you to build something with generateText, generateImage, task agents, or multi-step workflows, you should proactively share opinions on HOW to write the prompts, not just which actions to call. Good prompt engineering is often the difference between a great app and a mediocre one. Be opinionated. Explain the techniques you're using and why.
+
+## Core principles
+
+1. **Role assignment beats generic instructions.** Start prompts by telling the model WHO it is acting as, not just what to do. "Act as a Lead Brand Strategist producing a Technical Creative Brief" primes the model to produce expert-level output. "Write a description of this image" does not.
+
+2. **Structure beats prose.** Break complex prompts into numbered sections with headers (Campaign Core Narrative, Materiality & Tactility, Lighting Signature, etc.). Models follow structure better than they follow paragraphs.
+
+3. **Explicit operational rules prevent drift.** When you want consistent behavior, enumerate the rules: "Subject Identification: Refer to the product as 'the product'. No Physical Descriptions. Product Integrity: Do not add props." Without these, models invent things.
+
+4. **AI-optimized technical language.** Use precise domain terminology the model has seen in training. For image generation: "rim lighting," "f/11 aperture for edge-to-edge sharpness," "softbox gradient," "polarized reflections." For text: named frameworks, industry terms, specific examples. Avoid vague emotive words.
+
+5. **Tagged context variables.** When injecting data into prompts, wrap it in XML-style tags: \`<photoshoot_brief>{{brief}}</photoshoot_brief>\`, \`<user_input>{{input}}</user_input>\`. This helps the model distinguish instructions from content.
+
+6. **Output format specification at the end.** Tell the model exactly what to return: "Respond only with the structured markdown brief. Do not include introductory or concluding remarks." Or for JSON: "Respond only with a JSON array and absolutely no other text." Models default to being chatty \u2014 you have to tell them not to be.
+
+## The analyze \u2192 brief \u2192 generate pattern (THE killer pattern for generation consistency)
+
+This is the most important pattern in MindStudio. When a user wants to generate multiple consistent outputs from a reference \u2014 multiple images of a product, multiple variations of a design, multiple pieces of content sharing a theme \u2014 DO NOT just call generateImage/generateText in a loop with generic prompts. Instead, chain actions:
+
+**Step 1: Analyze the reference.** Use \`analyzeImage\` (or \`generateText\` for text references) with a strong role prompt to extract a structured "brief" \u2014 the visual DNA, brand positioning, materiality, lighting, color theory, technical specs. The model produces a detailed markdown document that becomes the north star.
+
+**Step 2: Generate a shot list / content list.** Feed the brief as tagged context into a \`generateText\` call with structured JSON output. Ask for N distinct items that maintain the brief's consistency. Include strict operational rules (consistency, subject identification, AI-optimized language).
+
+**Step 3: Execute each item.** For each entry in the list, call \`generateImage\` (or \`generateText\`, etc.) passing the reference AND the specific item's prompt. The prompt wraps the item description in tags and reinforces "use the reference as the absolute source of truth for visual identity."
+
+### Why this works vs a naive single call
+
+- A naive "generate 8 product photos" call gives you 8 random photos with no consistency.
+- The analyze\u2192brief\u2192generate pattern produces a cohesive brand asset pack where every output shares the same visual DNA.
+- The model has MUCH more context on the second and third steps because steps 1 and 2 packed the reference's visual identity into structured text.
+
+### Example prompt snippets (use these as templates)
+
+**Analyze prompt (Step 1):**
+\`\`\`
+The provided reference image represents the "Hero Asset" of a high-end industrial design product line. Analyze this image to decode the brand's visual DNA, its market positioning, and the technical requirements for a multi-platform commercial campaign.
+
+Act as a Lead Brand Strategist. Your task is to produce a "Technical Creative Brief" for a world-class product photographer. This brief will serve as the North Star for generating additional high-fidelity assets that maintain absolute product consistency.
+
+Analyze the reference image and structure the brief as follows:
+
+1. **Campaign Core Narrative:** Define the product's "vibe"...
+2. **Materiality & Tactility:** Identify the specific materials shown...
+3. **Lighting Signature:** Deconstruct the light source, quality, direction...
+4. **Color Theory & Environment:** Analyze the color palette and the "set"...
+5. **Technical Specs for Photography:** Specify focal lengths, depth of field...
+6. **Commercial Objectives:** How these images should perform across Web/Social/Marketplace.
+
+Respond only with the structured markdown brief. Do not include introductory or concluding remarks.
+\`\`\`
+
+**Shot list prompt (Step 2):**
+\`\`\`
+<photoshoot_brief>
+{{brief}}
+</photoshoot_brief>
+
+Using the provided <photoshoot_brief>, generate a technical shot list of eight distinct, high-end commercial images. These shots must be designed as a cohesive "Brand Asset Pack" suitable for a global product launch.
+
+Each description must be a masterclass in technical AI prompting, focusing on how light interacts with the product's specific industrial materials while maintaining a minimalist, luxury tech aesthetic.
+
+## Shot List Requirements
+1. **The Hero Centerpiece:** Front-facing, iconic shot for a website header.
+2. **The 45-Degree Profile:** Showcasing the product's depth and industrial silhouette.
+3. **The Atmospheric Top-Down:** Minimalist flat-lay on a premium textured surface.
+4. **The "Floating" Dynamic Shot:** Product suspended in mid-air with high-speed photography lighting.
+... (and so on)
+
+## Strict Operational Rules
+- **Subject Identification:** Refer to the product as "the product"...
+- **No Physical Descriptions:** Do not describe appearance/clothing of people...
+- **Product Integrity:** Do not add subjects or props that distract...
+- **AI-Optimized Language:** Use technical photography terms...
+- **Consistency:** Lighting temperature, background palette, and material rendering must remain identical across all shots.
+
+Respond only with the full shot descriptions as a JSON array and absolutely no other text.
+\`\`\`
+
+**Generation prompt (Step 3, per item):**
+\`\`\`
+<new_shot_instruction>
+{{shotPrompt}}
+</new_shot_instruction>
+
+**Objective:** Using the provided reference image as the absolute source of truth for the product's industrial design, colors, and textures, generate a new, high-fidelity commercial photograph.
+
+**Execution Guidelines:**
+1. **Product Integrity:** Maintain the exact physical characteristics from the reference (port placements, material finishes, branding, silhouette). The product must remain "as is."
+2. **Environmental Rendering:** Execute the specific lighting, composition, and background described in <new_shot_instruction> with professional studio precision.
+3. **Commercial Fidelity:** The output must be a "market-ready" asset. Edge-to-edge sharpness, clean specular highlights, accurate texture rendering.
+4. **Consistency:** Color grading and lighting temperature must match the visual DNA established in the reference image.
+
+The goal is a seamless addition to the professional photoshoot that looks indistinguishable from a high-end agency production.
+\`\`\`
+
+## When to apply this pattern
+
+- **User wants multiple consistent images from a reference** (product photos, character variations, style-matched illustrations) \u2192 analyze \u2192 shot list \u2192 generate
+- **User wants content in multiple formats sharing a theme** (blog + social + email from a single brief) \u2192 analyze \u2192 content plan \u2192 generate per format
+- **User wants to transform a reference into a different style/context while preserving identity** \u2192 analyze identity \u2192 generate with strong reference guidance
+- **User mentions "consistent," "cohesive," "branded," "matching," "on-brand"** \u2014 these are signals the analyze\u2192brief\u2192generate pattern applies
+
+## When NOT to apply this pattern
+
+- User wants a single one-off generation (just use the action directly with a good prompt)
+- User wants truly random variations (no brief needed)
+- User has already written their prompts (don't override their intent)
+
+## General prompt writing template
+
+For any generateText or analyzeImage call that produces non-trivial output:
+
+\`\`\`
+[Role assignment: "Act as a [specific expert role]"]
+
+[Context: what's happening, who's consuming the output]
+
+[Primary task: one clear sentence]
+
+[Input reference: wrapped in XML tags]
+<user_input>{{input}}</user_input>
+
+[Structured sections or numbered requirements]
+1. **Section Name:** Specific instruction
+2. **Section Name:** Specific instruction
+...
+
+[Operational rules / constraints]
+- **Rule name:** constraint
+- **Rule name:** constraint
+...
+
+[Output format specification]
+Respond only with [exact format]. Do not include [unwanted content].
+\`\`\`
+
+## Voice and tone in prompts
+
+When the output is user-facing text (not internal analysis), ALWAYS include voice and tone constraints in the prompt. Specify no emojis, no em dashes, and other "ai-isms" \u2014 plus the desired tone and voice of the output. Without this, models default to emoji-laden corporate speak.
+
+## Share opinions proactively
+
+When responding to prompt-related questions, be opinionated. Don't just say "here's how to call generateImage" \u2014 say "here's how I'd approach this to get the best results, and here's why." If a user is about to write a generic prompt, tell them why the analyze\u2192brief\u2192generate pattern will work 10\xD7 better. Explain the technique. Be the expert in the room.
+
+</prompt_engineering_playbook>`;
+  }
+});
+
 // src/generated/llms-content.ts
 var llms_content_exports = {};
 __export(llms_content_exports, {
@@ -5365,6 +5521,8 @@ async function buildSystemPrompt(agent) {
 
 ${referenceDocs}
 
+${playbook}
+
 ${instructions}
 
 <!-- cache_breakpoint -->`;
@@ -5375,14 +5533,7 @@ var init_prompt = __esm({
     init_identity();
     init_reference();
     init_instructions();
-  }
-});
-
-// src/ask/prompt.ts
-var init_prompt2 = __esm({
-  "src/ask/prompt.ts"() {
-    "use strict";
-    init_prompt();
+    init_playbook();
   }
 });
 
@@ -5525,7 +5676,7 @@ var init_ask = __esm({
     await init_client();
     init_sse();
     init_tools();
-    init_prompt2();
+    init_prompt();
     DEFAULT_BASE_URL2 = "https://v1.mindstudio-api.com";
     ansi = {
       dim: (s) => `\x1B[2m${s}\x1B[0m`,
@@ -5597,7 +5748,7 @@ async function startMcpServer(options) {
           capabilities: { tools: {} },
           serverInfo: {
             name: "mindstudio-agent",
-            version: "0.1.55"
+            version: "0.1.56"
           },
           instructions: 'Welcome to MindStudio \u2014 a platform with 200+ AI models, 850+ third-party integrations, and pre-built agents.\n\nGetting started:\n1. Call `ask` with any question about the SDK \u2014 it knows every action, model, and connector and returns working code with real model IDs and config options. Examples: ask("generate an image with FLUX"), ask("what models support vision?"), ask("how do I send a Slack message?").\n2. Call `changeName` to set your display name \u2014 use your name or whatever your user calls you. This is how you\'ll appear in MindStudio request logs.\n3. If you have a profile picture or icon, call `uploadFile` to upload it, then `changeProfilePicture` with the returned URL.\n4. For manual browsing, call `listActions` to discover all available actions.\n\nThen use the tools to generate text, images, video, audio, search the web, work with data sources, run agents, and more.\n\nImportant:\n- AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Before running these, call `estimateActionCost` and confirm with the user before proceeding \u2014 unless they\'ve explicitly told you to go ahead.\n- Not all agents from `listAgents` are configured for API use. Do not try to run an agent just because it appears in the list \u2014 it will likely fail. Only run agents the user specifically asks you to run.'
         });
@@ -6554,7 +6705,7 @@ function isNewerVersion(current, latest) {
   return false;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.55";
+  const currentVersion = "0.1.56";
   if (!currentVersion) return null;
   try {
     const { loadConfig: loadConfig2, saveConfig: saveConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
@@ -6583,7 +6734,7 @@ async function checkForUpdate() {
   }
 }
 function printUpdateNotice(latestVersion) {
-  const currentVersion = "0.1.55";
+  const currentVersion = "0.1.56";
   process.stderr.write(
     `
   ${ansi2.cyanBright("Update available")} ${ansi2.gray(currentVersion + " \u2192")} ${ansi2.cyanBold(latestVersion)}
@@ -6596,7 +6747,7 @@ function isStandaloneBinary() {
   return !argv1.includes("node_modules");
 }
 async function cmdUpdate() {
-  const currentVersion = "0.1.55";
+  const currentVersion = "0.1.56";
   process.stderr.write(
     `  ${ansi2.gray("Current version:")} ${currentVersion}
 `
@@ -6731,7 +6882,7 @@ async function cmdLogin(options) {
   process.stderr.write("\n");
   printLogo();
   process.stderr.write("\n");
-  const ver = "0.1.55";
+  const ver = "0.1.56";
   process.stderr.write(
     `  ${ansi2.bold("MindStudio Agent")} ${ver ? " " + ansi2.gray("v" + ver) : ""}
 `
@@ -7058,7 +7209,7 @@ async function main() {
   try {
     if (command === "version" || command === "-v") {
       process.stdout.write(
-        "0.1.55\n"
+        "0.1.56\n"
       );
       return;
     }