@mindstudio-ai/remy 0.1.20 → 0.1.21

package/dist/index.js

@@ -1012,12 +1012,42 @@ var init_confirmDestructiveAction = __esm({
   }
 });
 
-// src/subagents/sdkConsultant/index.ts
+// src/subagents/common/runCli.ts
 import { exec } from "child_process";
+function runCli(cmd, options) {
+  return new Promise((resolve) => {
+    exec(
+      cmd,
+      {
+        timeout: options?.timeout ?? 6e4,
+        maxBuffer: options?.maxBuffer ?? 1024 * 1024
+      },
+      (err, stdout, stderr) => {
+        if (stdout.trim()) {
+          resolve(stdout.trim());
+          return;
+        }
+        if (err) {
+          resolve(`Error: ${stderr.trim() || err.message}`);
+          return;
+        }
+        resolve("(no response)");
+      }
+    );
+  });
+}
+var init_runCli = __esm({
+  "src/subagents/common/runCli.ts"() {
+    "use strict";
+  }
+});
+
+// src/subagents/sdkConsultant/index.ts
 var askMindStudioSdkTool;
 var init_sdkConsultant = __esm({
   "src/subagents/sdkConsultant/index.ts"() {
     "use strict";
+    init_runCli();
     askMindStudioSdkTool = {
       definition: {
         name: "askMindStudioSdk",
@@ -1035,22 +1065,8 @@ var init_sdkConsultant = __esm({
       },
       async execute(input) {
         const query = input.query;
-        return new Promise((resolve) => {
-          exec(
-            `mindstudio ask ${JSON.stringify(query)}`,
-            { timeout: 6e4, maxBuffer: 512 * 1024 },
-            (err, stdout, stderr) => {
-              if (stdout.trim()) {
-                resolve(stdout.trim());
-                return;
-              }
-              if (err) {
-                resolve(`Error: ${stderr.trim() || err.message}`);
-                return;
-              }
-              resolve("(no response)");
-            }
-          );
+        return runCli(`mindstudio ask ${JSON.stringify(query)}`, {
+          maxBuffer: 512 * 1024
         });
       }
     };
@@ -1058,11 +1074,11 @@ var init_sdkConsultant = __esm({
 });
 
 // src/tools/common/fetchUrl.ts
-import { exec as exec2 } from "child_process";
 var fetchUrlTool;
 var init_fetchUrl = __esm({
   "src/tools/common/fetchUrl.ts"() {
     "use strict";
+    init_runCli();
     fetchUrlTool = {
       definition: {
         name: "scapeWebUrl",
@@ -1089,35 +1105,20 @@ var init_fetchUrl = __esm({
         if (screenshot) {
           pageOptions.screenshot = true;
         }
-        const cmd = `mindstudio scrape-url --url ${JSON.stringify(url)} --page-options ${JSON.stringify(JSON.stringify(pageOptions))} --no-meta`;
-        return new Promise((resolve) => {
-          exec2(
-            cmd,
-            { timeout: 6e4, maxBuffer: 1024 * 1024 },
-            (err, stdout, stderr) => {
-              if (stdout.trim()) {
-                resolve(stdout.trim());
-                return;
-              }
-              if (err) {
-                resolve(`Error: ${stderr.trim() || err.message}`);
-                return;
-              }
-              resolve("(no response)");
-            }
-          );
-        });
+        return runCli(
+          `mindstudio scrape-url --url ${JSON.stringify(url)} --page-options ${JSON.stringify(JSON.stringify(pageOptions))} --no-meta`
+        );
       }
     };
   }
 });
 
 // src/tools/common/searchGoogle.ts
-import { exec as exec3 } from "child_process";
 var searchGoogleTool;
 var init_searchGoogle = __esm({
   "src/tools/common/searchGoogle.ts"() {
     "use strict";
+    init_runCli();
     searchGoogleTool = {
       definition: {
         name: "searchGoogle",
@@ -1135,24 +1136,10 @@ var init_searchGoogle = __esm({
       },
       async execute(input) {
         const query = input.query;
-        const cmd = `mindstudio search-google --query ${JSON.stringify(query)} --export-type json --output-key results --no-meta`;
-        return new Promise((resolve) => {
-          exec3(
-            cmd,
-            { timeout: 6e4, maxBuffer: 512 * 1024 },
-            (err, stdout, stderr) => {
-              if (stdout.trim()) {
-                resolve(stdout.trim());
-                return;
-              }
-              if (err) {
-                resolve(`Error: ${stderr.trim() || err.message}`);
-                return;
-              }
-              resolve("(no response)");
-            }
-          );
-        });
+        return runCli(
+          `mindstudio search-google --query ${JSON.stringify(query)} --export-type json --output-key results --no-meta`,
+          { maxBuffer: 512 * 1024 }
+        );
       }
     };
   }
@@ -1509,7 +1496,7 @@ ${unifiedDiff(input.path, content, updated)}`;
 });
 
 // src/tools/code/bash.ts
-import { exec as exec4 } from "child_process";
+import { exec as exec2 } from "child_process";
 var DEFAULT_TIMEOUT_MS, DEFAULT_MAX_LINES3, bashTool;
 var init_bash = __esm({
   "src/tools/code/bash.ts"() {
@@ -1547,7 +1534,7 @@ var init_bash = __esm({
         const maxLines = input.maxLines === 0 ? Infinity : input.maxLines || DEFAULT_MAX_LINES3;
         const timeoutMs = input.timeout ? input.timeout * 1e3 : DEFAULT_TIMEOUT_MS;
         return new Promise((resolve) => {
-          exec4(
+          exec2(
             input.command,
             {
               timeout: timeoutMs,
@@ -1589,7 +1576,7 @@ var init_bash = __esm({
 });
 
 // src/tools/code/grep.ts
-import { exec as exec5 } from "child_process";
+import { exec as exec3 } from "child_process";
 function formatResults(stdout, max) {
   const lines = stdout.trim().split("\n");
   let result = lines.join("\n");
@@ -1640,12 +1627,12 @@ var init_grep = __esm({
         const rgCmd = `rg -n --no-heading --max-count=${max}${globFlag} '${escaped}' ${searchPath}`;
         const grepCmd = `grep -rn --max-count=${max} '${escaped}' ${searchPath} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md'`;
         return new Promise((resolve) => {
-          exec5(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
+          exec3(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
             if (stdout?.trim()) {
               resolve(formatResults(stdout, max));
               return;
             }
-            exec5(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
+            exec3(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
               if (grepStdout?.trim()) {
                 resolve(formatResults(grepStdout, max));
               } else {
@@ -1980,21 +1967,44 @@ var init_runMethod = __esm({
 });
 
 // src/tools/code/screenshot.ts
-var screenshotTool;
+var DEFAULT_PROMPT, screenshotTool;
 var init_screenshot = __esm({
   "src/tools/code/screenshot.ts"() {
     "use strict";
+    init_sidecar();
+    init_runCli();
+    DEFAULT_PROMPT = "Describe this app screenshot for a developer who cannot see it. What is visible on screen: the layout, content, interactive elements, any loading or error states. Be concise and factual.";
     screenshotTool = {
       definition: {
         name: "screenshot",
-        description: "Capture a screenshot of the app preview. Returns a CDN URL with dimensions. Useful for visually checking the current state after UI changes or when debugging layout issues.",
+        description: "Capture a screenshot of the app preview and get a description of what's on screen. Optionally provide a specific question about what you're looking for.",
         inputSchema: {
           type: "object",
-          properties: {}
+          properties: {
+            prompt: {
+              type: "string",
+              description: "Optional question about the screenshot. If omitted, returns a general description of what's visible."
+            }
+          }
         }
       },
-      async execute() {
-        return "ok";
+      async execute(input) {
+        try {
+          const { url } = await sidecarRequest(
+            "/screenshot",
+            {},
+            { timeout: 3e4 }
+          );
+          const analysisPrompt = input.prompt || DEFAULT_PROMPT;
+          const analysis = await runCli(
+            `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
+          );
+          return `Screenshot: ${url}
+
+${analysis}`;
+        } catch (err) {
+          return `Error taking screenshot: ${err.message}`;
+        }
       }
     };
   }
@@ -2385,28 +2395,26 @@ var init_browserAutomation = __esm({
 });
 
 // src/subagents/designExpert/tools.ts
-import { exec as exec6 } from "child_process";
-function runCli(cmd) {
-  return new Promise((resolve) => {
-    exec6(
-      cmd,
-      { timeout: 6e4, maxBuffer: 1024 * 1024 },
-      (err, stdout, stderr) => {
-        if (stdout.trim()) {
-          resolve(stdout.trim());
-          return;
-        }
-        if (err) {
-          resolve(`Error: ${stderr.trim() || err.message}`);
-          return;
-        }
-        resolve("(no response)");
-      }
-    );
-  });
-}
-async function executeDesignTool(name, input) {
+async function executeDesignExpertTool(name, input) {
   switch (name) {
+    case "screenshot": {
+      try {
+        const { url } = await sidecarRequest(
+          "/screenshot",
+          {},
+          { timeout: 3e4 }
+        );
+        const analysisPrompt = input.prompt || "Describe this app screenshot for a visual designer reviewing the current state. What is visible: layout, typography, colors, spacing, imagery. Note anything that looks broken or off. Be concise.";
+        const analysis = await runCli(
+          `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
+        );
+        return `Screenshot: ${url}
+
+${analysis}`;
+      } catch (err) {
+        return `Error taking screenshot: ${err.message}`;
+      }
+    }
     case "searchGoogle":
       return runCli(
         `mindstudio search-google --query ${JSON.stringify(input.query)} --export-type json --output-key results --no-meta`
@@ -2451,6 +2459,8 @@ ${analysis}`;
       const prompts = input.prompts;
       const width = input.width || 2048;
       const height = input.height || 2048;
+      const ANALYZE_PROMPT = "You are reviewing this image for a visual designer sourcing assets for a project. Describe: what the image depicts, the mood and color palette, how the lighting and composition work, whether there are any issues (unwanted text, artifacts, distortions), and how it could be used in a layout (hero background, feature section, card texture, etc). Be concise and practical.";
+      let imageUrls;
       if (prompts.length === 1) {
         const step = JSON.stringify({
           prompt: prompts[0],
@@ -2459,30 +2469,58 @@ ${analysis}`;
             config: { width, height }
           }
         });
-        return runCli(
+        const url = await runCli(
           `mindstudio generate-image '${step}' --output-key imageUrl --no-meta`
         );
-      }
-      const steps = prompts.map((prompt) => ({
-        stepType: "generateImage",
-        step: {
-          prompt,
-          imageModelOverride: {
-            model: "seedream-4.5",
-            config: { width, height }
+        imageUrls = [url];
+      } else {
+        const steps = prompts.map((prompt) => ({
+          stepType: "generateImage",
+          step: {
+            prompt,
+            imageModelOverride: {
+              model: "seedream-4.5",
+              config: { width, height }
+            }
           }
+        }));
+        const batchResult = await runCli(
+          `mindstudio batch '${JSON.stringify(steps)}' --no-meta`
+        );
+        try {
+          const parsed = JSON.parse(batchResult);
+          imageUrls = parsed.results.map(
+            (r) => r.output?.imageUrl ?? `Error: ${r.error}`
+          );
+        } catch {
+          return batchResult;
         }
-      }));
-      return runCli(`mindstudio batch '${JSON.stringify(steps)}' --no-meta`);
+      }
+      const analyses = await Promise.all(
+        imageUrls.map(async (url, i) => {
+          if (url.startsWith("Error")) {
+            return `Image ${i + 1}: ${url}`;
+          }
+          const analysis = await runCli(
+            `mindstudio analyze-image --prompt ${JSON.stringify(ANALYZE_PROMPT)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
+          );
+          return `**Image ${i + 1}:** ${url}
+Prompt: ${prompts[i]}
+Analysis: ${analysis}`;
+        })
+      );
+      return analyses.join("\n\n");
     }
     default:
       return `Error: unknown tool "${name}"`;
   }
 }
-var DESIGN_REFERENCE_PROMPT, DESIGN_RESEARCH_TOOLS;
+var DESIGN_REFERENCE_PROMPT, DESIGN_EXPERT_TOOLS;
 var init_tools2 = __esm({
   "src/subagents/designExpert/tools.ts"() {
     "use strict";
+    init_runCli();
+    init_sidecar();
     DESIGN_REFERENCE_PROMPT = `Analyze this website/app screenshot as a design reference. Assess:
 1) Mood/aesthetic
 2) Color palette with approximate hex values and palette strategy
@@ -2490,7 +2528,7 @@ var init_tools2 = __esm({
 4) Layout composition (symmetric/asymmetric, grid structure, whitespace usage, content density)
 5) What makes it distinctive and interesting vs generic AI-generated interfaces
 Be specific and concise.`;
-    DESIGN_RESEARCH_TOOLS = [
+    DESIGN_EXPERT_TOOLS = [
       {
         name: "searchGoogle",
         description: "Search Google for web results. Use for finding design inspiration, font recommendations, UI patterns, real products in a domain, and reference material.",
@@ -2565,7 +2603,7 @@ Be specific and concise.`;
       },
       {
         name: "generateImages",
-        description: "Generate images using AI (Seedream). Returns CDN URLs. Produces high-quality results for both photorealistic images and abstract/creative visuals. Pass multiple prompts to generate in parallel.",
+        description: "Generate images using AI (Seedream). Returns CDN URLs with a quality analysis for each image. Produces high-quality results for both photorealistic images and abstract/creative visuals. Pass multiple prompts to generate in parallel. No need to analyze images separately after generating \u2014 the analysis is included.",
         inputSchema: {
           type: "object",
           properties: {
@@ -2721,7 +2759,7 @@ function sample(arr, n) {
   }
   return copy.slice(0, n);
 }
-function getDesignResearchPrompt() {
+function getDesignExpertPrompt() {
   const fonts = sample(fontData.fonts, 30);
   const pairings = sample(fontData.pairings, 20);
   const images = sample(inspirationImages, 15);
@@ -2806,7 +2844,7 @@ var init_designExpert = __esm({
     init_tools2();
     init_prompt2();
     DESCRIPTION = `
-Visual design expert. Handles fonts, colors, palettes, gradients, layouts, imagery, icons, and visual direction. Can answer from expertise alone or research the web. Returns concrete resources: hex values, font names with CSS URLs, image URLs, layout descriptions. Include app context in your task \u2014 the agent cannot see your conversation with the user.
+Visual design expert. Describe the situation and what you need \u2014 the agent decides what to deliver. It reads the spec files automatically. Include relevant user requirements and context it can't get from the spec, but do not list specific deliverables or tell it how to do its job.
 `.trim();
     designExpertTool = {
       definition: {
@@ -2825,17 +2863,17 @@ Visual design expert. Handles fonts, colors, palettes, gradients, layouts, image
       },
       async execute(input, context) {
         if (!context) {
-          return "Error: design research requires execution context";
+          return "Error: visual design expert requires execution context";
         }
         const result = await runSubAgent({
-          system: getDesignResearchPrompt(),
+          system: getDesignExpertPrompt(),
           task: input.task,
-          tools: DESIGN_RESEARCH_TOOLS,
-          externalTools: /* @__PURE__ */ new Set(["screenshot"]),
-          executeTool: executeDesignTool,
+          tools: DESIGN_EXPERT_TOOLS,
+          externalTools: /* @__PURE__ */ new Set(),
+          executeTool: executeDesignExpertTool,
           apiConfig: context.apiConfig,
           model: context.model,
-          subAgentId: "designExpert",
+          subAgentId: "visualDesignExpert",
           signal: context.signal,
           parentToolId: context.toolCallId,
           onEvent: context.onEvent,
@@ -3843,6 +3881,12 @@ async function runTurn(params) {
     });
   }
   state.messages.push(userMsg);
+  const STATUS_EXCLUDED_TOOLS = /* @__PURE__ */ new Set([
+    "setProjectOnboardingState",
+    "setProjectName",
+    "clearSyncStatus",
+    "editsFinished"
+  ]);
   let lastCompletedTools = "";
   let lastCompletedResult = "";
   while (true) {
@@ -3931,7 +3975,7 @@ async function runTurn(params) {
       apiConfig,
       getContext: () => ({
         assistantText: getTextContent(contentBlocks).slice(-500),
-        lastToolName: getToolCalls(contentBlocks).at(-1)?.name || lastCompletedTools || void 0,
+        lastToolName: getToolCalls(contentBlocks).filter((tc) => !STATUS_EXCLUDED_TOOLS.has(tc.name)).at(-1)?.name || lastCompletedTools || void 0,
         lastToolResult: lastCompletedResult || void 0
       }),
       onStatus: (label) => onEvent({ type: "status", message: label }),
@@ -4090,6 +4134,28 @@ async function runTurn(params) {
       count: toolCalls.length,
       tools: toolCalls.map((tc) => tc.name)
     });
+    let subAgentText = "";
+    const origOnEvent = onEvent;
+    const wrappedOnEvent = (e) => {
+      if ("parentToolId" in e && e.parentToolId) {
+        if (e.type === "text") {
+          subAgentText = e.text;
+        } else if (e.type === "tool_start") {
+          subAgentText = `Using ${e.name}`;
+        }
+      }
+      origOnEvent(e);
+    };
+    const toolStatusWatcher = startStatusWatcher({
+      apiConfig,
+      getContext: () => ({
+        assistantText: subAgentText || getTextContent(contentBlocks).slice(-500),
+        lastToolName: toolCalls.filter((tc) => !STATUS_EXCLUDED_TOOLS.has(tc.name)).map((tc) => tc.name).join(", ") || void 0,
+        lastToolResult: lastCompletedResult || void 0
+      }),
+      onStatus: (label) => origOnEvent({ type: "status", message: label }),
+      signal
+    });
     const subAgentMessages = /* @__PURE__ */ new Map();
     const results = await Promise.all(
       toolCalls.map(async (tc) => {
@@ -4115,7 +4181,7 @@ async function runTurn(params) {
               apiConfig,
               model,
               signal,
-              onEvent,
+              onEvent: wrappedOnEvent,
               resolveExternalTool,
               toolCallId: tc.id,
               subAgentMessages
@@ -4149,15 +4215,21 @@ async function runTurn(params) {
         }
       })
     );
-    for (const [toolId, msgs] of subAgentMessages) {
+    toolStatusWatcher.stop();
+    for (const r of results) {
       const block = contentBlocks.find(
-        (b) => b.type === "tool" && b.id === toolId
+        (b) => b.type === "tool" && b.id === r.id
       );
       if (block?.type === "tool") {
-        block.subAgentMessages = msgs;
+        block.result = r.result;
+        block.isError = r.isError;
+        const msgs = subAgentMessages.get(r.id);
+        if (msgs) {
+          block.subAgentMessages = msgs;
+        }
       }
     }
-    lastCompletedTools = toolCalls.map((tc) => tc.name).join(", ");
+    lastCompletedTools = toolCalls.filter((tc) => !STATUS_EXCLUDED_TOOLS.has(tc.name)).map((tc) => tc.name).join(", ");
     lastCompletedResult = results.at(-1)?.result ?? "";
     for (const r of results) {
       state.messages.push({
@@ -4197,7 +4269,6 @@ var init_agent = __esm({
       "runScenario",
       "runMethod",
       "browserCommand",
-      "screenshot",
       "setProjectName"
     ]);
   }

package/dist/prompt/.notes.md

@@ -142,7 +142,7 @@ The intro framing ("you have a lot on your plate") gives the model permission to
 
 | Agent | Role | Tools | Context |
 |---|---|---|---|
-| `designExpert` | Visual design decisions | searchGoogle, fetchUrl, analyzeImage, screenshotAndAnalyze, searchProductScreenshots, generateImages | Spec files + sampled fonts + sampled inspiration |
+| `visualDesignExpert` | Visual design decisions | searchGoogle, fetchUrl, analyzeReferenceImageOrUrl, screenshot, searchProductScreenshots, generateImages | Spec files + sampled fonts + sampled inspiration |
 | `productVision` | Roadmap ownership & product strategy | writeRoadmapItem, updateRoadmapItem, deleteRoadmapItem | Spec files + current roadmap |
 | `sdkConsultant` | MindStudio SDK architecture | None (shells out to `mindstudio ask` CLI) | None (external agent) |
 | `codeSanityCheck` | Pre-build review | readFile, grep, glob, searchGoogle, fetchUrl, askMindStudioSdk, bash (readonly) | Spec files |

package/dist/prompt/compiled/design.md

@@ -43,7 +43,7 @@ Derive additional implementation colors (borders, focus states, hover states, di
 
 ### Typography block format
 
-A `` ```typography `` fenced block in a `type: design/typography` spec file declares fonts (with source URLs) and one or two anchor styles (typically Display and Body). Derive additional styles (labels, buttons, captions, overlines) from these anchors:
+A `` ```typography `` fenced block in a `type: design/typography` spec file declares fonts (with source URLs) and one or two anchor styles (typically Display and Body). Styles can include an optional `case` field (`uppercase`, `lowercase`, `capitalize`) for text-transform. Derive additional styles (labels, buttons, captions, overlines) from these anchors:
 
 ```typography
 fonts:
@@ -59,6 +59,7 @@ styles:
     weight: 600
     letterSpacing: -0.03em
     lineHeight: 1.1
+    case: uppercase
     description: Page titles and hero text
   Body:
     font: Satoshi

package/dist/prompt/compiled/msfm.md

@@ -181,6 +181,7 @@ styles:
     weight: 600
     letterSpacing: -0.03em
     lineHeight: 1.1
+    case: uppercase
     description: Page titles and hero text
   Body:
     font: Satoshi

package/dist/prompt/sources/frontend-design-notes.md

@@ -55,6 +55,7 @@ styles:
     weight: 600
     letterSpacing: -0.03em
     lineHeight: 1.1
+    case: uppercase
     description: Page titles and hero text
   Body:
     font: Satoshi

package/dist/prompt/static/authoring.md

@@ -3,7 +3,7 @@
 The spec is the application. It defines what the app does — the data, the workflows, the roles, the edge cases — and how it looks and feels. Code is derived from it. Your job is to help the user build a spec that's complete enough to compile into a working app.
 
 **Writing the first draft:**
-After intake, write the spec and get it on screen. The first draft should cover the full shape of the app — it's better to have every section roughed in than to have one section perfect and the rest missing.
+After intake, write the spec immediately. Do not ask "ready for me to start?" or wait for confirmation — just start writing. The first draft should cover the full shape of the app — it's better to have every section roughed in than to have one section perfect and the rest missing.
 
 - Make concrete decisions rather than leaving things vague. The user can change a decision; they can't react to vagueness.
 - Flag assumptions you made during intake so the user can confirm or correct them.
@@ -23,9 +23,9 @@ Start from these and extend as needed. Add interface specs for other interface t
 
 Users often care about look and feel as much as (or more than) underlying data structures. Don't treat the brand and interface specs as an afterthought — for many users, the visual identity and voice are the first things they want to get right.
 
-Write specs in natural, human language. Describe what the app does the way you'd explain it to a colleague. The spec rendered with annotations hidden is a human-forward document that anyone can read. The spec with annotations visible is the agent-forward document that drives code generation. Keep the prose clean and readable — technical details like column types, status values, CSS properties, code snippets, and implementation hints belong in annotations, not in the prose.
+Write specs in natural, human language. Describe what the app does the way you'd explain it to a colleague. The spec rendered with annotations hidden is a human-forward document that anyone can read. The spec with annotations visible is the agent-forward document that drives code generation. Keep the prose clean and readable — the user should never see raw CSS, code, or technical values in the prose. Write "square corners on all cards" not `border-radius: 0`. Write "no shadows" not `box-shadow: none`. Technical specifics belong in annotations.
 
-When you have image URLs (from the design expert, stock photos, or AI generation), embed them directly in the spec using markdown image syntax. Write descriptive alt text that captures what the image actually depicts (this helps accessibility and helps the coding agent understand the image without loading it). Use the surrounding prose to explain the design intent — what the image is for, how it should be used in the layout, and why it was chosen.
+When you have image URLs (from the design expert), embed them directly in the spec using markdown image syntax. Write descriptive alt text that captures what the image actually depicts (this helps accessibility and helps the coding agent understand the image without loading it). Use the surrounding prose to explain the design intent — what the image is for, how it should be used in the layout, and why it was chosen.
 
 ```markdown
 ### Hero Section
@@ -78,7 +78,7 @@ The body is freeform MSFM: prose describing the feature for the user, annotation
 
 The MVP itself gets a roadmap file (`src/roadmap/mvp.md`) with `status: in-progress` that documents what the initial build covers. Update it to `done` after the build completes. Other items start as `not-started`. Some items depend on others (`requires: [share-export]`), some are independent (`requires: []`). The user picks what to build next.
 
-The `productVision` tool owns `src/roadmap/` — see the Team section for when and how to use it.
+The `productVision` tool owns `src/roadmap/` — see the Team section for when and how to use it. As the final step of spec authoring, after all other spec files are written, call it to seed the initial roadmap.
 
 ## Spec + Code Sync
 

package/dist/prompt/static/team.md

@@ -2,6 +2,10 @@
 
 You have a lot on your plate — specs, code, tables, interfaces, scenarios, debugging, user communication. You don't need to do everything yourself. You are fortunate to have specialists who are genuinely better than you in their specific domains. Use them liberally — for quick questions, big projects, second opinions, and everything in between. These are not scarce resources. A one-line question is just as valid as a comprehensive brief. The more you delegate, the better the results.
 
+When delegating, describe the situation and what you need — not how to do it. Your specialists are experts. Trust them and give them space to impress you. They read the spec files automatically. They decide what to deliver, how many options to propose, and what approach to take. Keep task descriptions brief and focused on context: what the app is, who it's for, what the user wants. Do not constrain their output, specify quantities, or list requirements they should already know.
+
+Note: when you talk about the team to the user, refer to them by their name or as agents: "my design expert" or "let me bring in a specialized agent for QA" etc.
+
 ### Design Expert (`visualDesignExpert`)
 
 Your designer. Consult for any visual decision — choosing a color, picking fonts, proposing a layout, generating images, reviewing whether something looks good. Not just during intake or big design moments. If you're about to write CSS and you're not sure about a color, ask. If you just built a page and want a gut check, take a screenshot and send it over. If the user says "I don't like how this looks," ask the design expert what to change rather than guessing yourself, or if they say "I want a different image," that's the designer's problem, not yours.
@@ -16,7 +20,7 @@ Always consult the design expert during intake and before building any new produ
 
 Your product thinking partner. Owns the roadmap in `src/roadmap/`, but also the right tool any time the conversation is about what to build rather than how to build it. Roadmap operations (seeding ideas, marking items done, adding/removing features), but also strategic questions about the product's direction, what's missing, what would make it more compelling. It reads spec and roadmap files automatically. Describe the situation and let it decide what to do.
 
-### SDK Consultant (`askMindStudioSdk`)
+### Mindstudio SDK Consultant (`askMindStudioSdk`)
 
 Your architect for anything that touches external services, AI models, media processing, communication, or third-party APIs. Consult before you reach for an npm package, write boilerplate API code, or try to install system tools. The MindStudio SDK has 200+ managed actions for calling AI models, processing media, sending email/SMS, connecting to third-party APIs, web scraping, and much more. The SDK is already installed and authenticated in the execution environment — no API keys, no configuration, no setup. It handles all the operational complexity so you don't have to. Your instinct will be "I can just write this myself" — but the managed action is almost always the better architectural choice.
 
@@ -24,12 +28,12 @@ Also critical: model IDs in the MindStudio API do not match vendor API model IDs
 
 Describe what you're building at the method level — the full workflow — and get back architectural guidance and working code.
 
-### Code Sanity Check (`codeSanityCheck`)
+### Architecture Expert (aka Code Sanity Check) (`codeSanityCheck`)
 
 A quick gut check. Describe what you're about to build and how, and get back a brief review. Most of the time it'll literally jus say "lgtm." Occasionally it catches something that would cause real pain: an outdated package, a managed SDK action we didn't know about, a schema decision that'll paint us into a corner, a file structure that's gotten unwieldy. It can search the web, read the codebase, and check the SDK. 
 
 Always consult the code sanity check before writing code in initialCodegen with your proposed architecture.
 
-### Browser Testing (`runAutomatedBrowserTest`)
+### QA (`runAutomatedBrowserTest`)
 
 For verifying interactive flows that can't be confirmed from a static screenshot, or reproducing user-reported issues you can't identify from code alone. Run a scenario first to seed test data and set user roles.