@synergenius/flow-weaver 0.7.0 → 0.8.0

package/dist/cli/flow-weaver.mjs

@@ -30993,11 +30993,6 @@ var AnnotationGenerator = class {
     if (workflow.ui?.startNode?.x !== void 0 && workflow.ui?.startNode?.y !== void 0) {
       lines.push(` * @position Start ${Math.round(workflow.ui.startNode.x)} ${Math.round(workflow.ui.startNode.y)}`);
     }
-    workflow.instances.forEach((instance) => {
-      if (instance.config?.x !== void 0 && instance.config?.y !== void 0) {
-        lines.push(` * @position ${instance.id} ${Math.round(instance.config.x)} ${Math.round(instance.config.y)}`);
-      }
-    });
     if (workflow.ui?.exitNode?.x !== void 0 && workflow.ui?.exitNode?.y !== void 0) {
       lines.push(` * @position Exit ${Math.round(workflow.ui.exitNode.x)} ${Math.round(workflow.ui.exitNode.y)}`);
     }
@@ -31212,7 +31207,11 @@ function generateNodeInstanceTag(instance) {
   if (instance.config?.width !== void 0 && instance.config?.height !== void 0) {
     sizeAttr = ` [size: ${Math.round(instance.config.width)} ${Math.round(instance.config.height)}]`;
   }
-  return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}`;
+  let positionAttr = "";
+  if (instance.config?.x !== void 0 && instance.config?.y !== void 0) {
+    positionAttr = ` [position: ${Math.round(instance.config.x)} ${Math.round(instance.config.y)}]`;
+  }
+  return ` * @node ${instance.id} ${instance.nodeType}${parent}${labelAttr}${portOrderAttr}${portLabelAttr}${exprAttr}${pullExecutionAttr}${minimizedAttr}${colorAttr}${iconAttr}${tagsAttr}${sizeAttr}${positionAttr}`;
 }
 var annotationGenerator = new AnnotationGenerator();
 
@@ -32067,13 +32066,28 @@ function generateWorkflowJSDoc(ast, options = {}) {
     }
     lines.push(` * @fwImport ${npmType.name} ${actualFunctionName} from "${npmType.importSource}"`);
   }
+  const autoPositions = computeAutoPositions(ast);
   for (const instance of ast.instances) {
     if (macroInstanceIds.has(instance.id)) continue;
-    if (macroChildIds.has(instance.id) && instance.parent) {
-      const stripped = { ...instance, parent: void 0 };
+    let inst = instance;
+    if (inst.config?.x === void 0 || inst.config?.y === void 0) {
+      const autoPos = autoPositions.get(inst.id);
+      if (autoPos) {
+        inst = {
+          ...inst,
+          config: {
+            ...inst.config,
+            x: inst.config?.x ?? autoPos.x,
+            y: inst.config?.y ?? autoPos.y
+          }
+        };
+      }
+    }
+    if (macroChildIds.has(inst.id) && inst.parent) {
+      const stripped = { ...inst, parent: void 0 };
       lines.push(generateNodeInstanceTag(stripped));
     } else {
-      lines.push(generateNodeInstanceTag(instance));
+      lines.push(generateNodeInstanceTag(inst));
     }
   }
   const existingMacros = filterStaleMacros(
@@ -32116,22 +32130,11 @@ function generateWorkflowJSDoc(ast, options = {}) {
       }
     }
   }
-  const autoPositions = computeAutoPositions(ast);
   const startX = ast.ui?.startNode?.x ?? autoPositions.get("Start")?.x;
   const startY = ast.ui?.startNode?.y ?? autoPositions.get("Start")?.y;
   if (startX !== void 0 && startY !== void 0) {
     lines.push(` * @position Start ${Math.round(startX)} ${Math.round(startY)}`);
   }
-  for (const instance of ast.instances) {
-    const explicitX = instance.config?.x;
-    const explicitY = instance.config?.y;
-    const autoPos = autoPositions.get(instance.id);
-    const x = explicitX ?? autoPos?.x;
-    const y = explicitY ?? autoPos?.y;
-    if (x !== void 0 && y !== void 0) {
-      lines.push(` * @position ${instance.id} ${Math.round(x)} ${Math.round(y)}`);
-    }
-  }
   const exitX = ast.ui?.exitNode?.x ?? autoPositions.get("Exit")?.x;
   const exitY = ast.ui?.exitNode?.y ?? autoPositions.get("Exit")?.y;
   if (exitX !== void 0 && exitY !== void 0) {
@@ -41796,6 +41799,10 @@ var SizePrefix = createToken({
   name: "SizePrefix",
   pattern: /size:/
 });
+var PositionPrefix = createToken({
+  name: "PositionPrefix",
+  pattern: /position:/
+});
 var ColorPrefix = createToken({
   name: "ColorPrefix",
   pattern: /color:/
@@ -41970,6 +41977,7 @@ var allTokens = [
   MergeStrategyPrefix,
   PullExecutionPrefix,
   SizePrefix,
+  PositionPrefix,
   ColorPrefix,
   IconPrefix,
   TagsPrefix,
@@ -42408,6 +42416,7 @@ var NodeParser = class extends CstParser {
           { ALT: () => this.SUBRULE(this.minimizedAttr) },
           { ALT: () => this.SUBRULE(this.pullExecutionAttr) },
           { ALT: () => this.SUBRULE(this.sizeAttr) },
+          { ALT: () => this.SUBRULE(this.positionAttr) },
           { ALT: () => this.SUBRULE(this.colorAttr) },
           { ALT: () => this.SUBRULE(this.iconAttr) },
           { ALT: () => this.SUBRULE(this.tagsAttr) }
@@ -42500,6 +42509,12 @@ var NodeParser = class extends CstParser {
     this.CONSUME(Integer, { LABEL: "widthValue" });
     this.CONSUME2(Integer, { LABEL: "heightValue" });
   });
+  // position: x y
+  positionAttr = this.RULE("positionAttr", () => {
+    this.CONSUME(PositionPrefix);
+    this.CONSUME(Integer, { LABEL: "xValue" });
+    this.CONSUME2(Integer, { LABEL: "yValue" });
+  });
   // color: "value"
   colorAttr = this.RULE("colorAttr", () => {
     this.CONSUME(ColorPrefix);
@@ -42546,6 +42561,7 @@ var NodeVisitor = class extends BaseVisitor2 {
     let minimized;
     let pullExecution;
     let size;
+    let position;
     let color;
     let icon;
     let tags;
@@ -42562,6 +42578,7 @@ var NodeVisitor = class extends BaseVisitor2 {
         if (attrs.minimized) minimized = attrs.minimized;
         if (attrs.pullExecution) pullExecution = attrs.pullExecution;
         if (attrs.size) size = attrs.size;
+        if (attrs.position) position = attrs.position;
         if (attrs.color) color = attrs.color;
         if (attrs.icon) icon = attrs.icon;
         if (attrs.tags) tags = [...tags || [], ...attrs.tags];
@@ -42578,6 +42595,7 @@ var NodeVisitor = class extends BaseVisitor2 {
       ...minimized && { minimized },
       ...pullExecution && { pullExecution },
       ...size && { size },
+      ...position && { position },
       ...color && { color },
       ...icon && { icon },
       ...tags && { tags }
@@ -42596,6 +42614,7 @@ var NodeVisitor = class extends BaseVisitor2 {
     let minimized;
     let pullExecution;
     let size;
+    let position;
     let color;
     let icon;
     let tags;
@@ -42635,6 +42654,11 @@ var NodeVisitor = class extends BaseVisitor2 {
         size = this.visit(attr);
       }
     }
+    if (ctx.positionAttr) {
+      for (const attr of ctx.positionAttr) {
+        position = this.visit(attr);
+      }
+    }
     if (ctx.colorAttr) {
       for (const attr of ctx.colorAttr) {
         color = this.visit(attr);
@@ -42659,6 +42683,7 @@ var NodeVisitor = class extends BaseVisitor2 {
       minimized,
       pullExecution,
       size,
+      position,
       color,
       icon,
       tags
@@ -42732,6 +42757,11 @@ var NodeVisitor = class extends BaseVisitor2 {
     const height4 = parseInt(ctx.heightValue[0].image, 10);
     return { width, height: height4 };
   }
+  positionAttr(ctx) {
+    const x = parseInt(ctx.xValue[0].image, 10);
+    const y = parseInt(ctx.yValue[0].image, 10);
+    return { x, y };
+  }
   colorAttr(ctx) {
     return this.unescapeString(ctx.colorValue[0].image);
   }
@@ -44417,6 +44447,7 @@ var JSDocParser = class {
       minimized,
       pullExecution,
       size,
+      position,
       color,
       icon,
       tags
@@ -44463,6 +44494,7 @@ var JSDocParser = class {
       ...icon && { icon },
       ...tags && tags.length > 0 && { tags },
       ...size && { width: size.width, height: size.height },
+      ...position && { x: position.x, y: position.y },
       sourceLocation: { line, column: 0 }
     });
   }
@@ -44479,6 +44511,11 @@ var JSDocParser = class {
     }
     const { nodeId, x, y } = result;
     config2.positions[nodeId] = { x, y };
+    if (nodeId !== "Start" && nodeId !== "Exit") {
+      warnings.push(
+        `Deprecated: @position ${nodeId} \u2014 use [position: ${x} ${y}] on the @node declaration instead.`
+      );
+    }
   }
   /**
    * Parse @connect tag using Chevrotain parser.
@@ -45670,6 +45707,7 @@ ${fn.getText()}` : fn.getText();
           ...parent && { parent },
           config: {
             ...inst.label && { label: inst.label },
+            ...inst.x !== void 0 && inst.y !== void 0 && { x: inst.x, y: inst.y },
             ...position && { x: position.x, y: position.y },
             ...portConfigs && portConfigs.length > 0 && { portConfigs },
             ...inst.pullExecution && { pullExecution: inst.pullExecution },
@@ -48585,13 +48623,10 @@ function outputResult(data: any): { result: any } {
 
 /**
  * @flowWeaver workflow
- * @node validator validateData
- * @node transformer transformData
- * @node outputter outputResult
+ * @node validator validateData [position: -300 0]
+ * @node transformer transformData [position: 0 0]
+ * @node outputter outputResult [position: 300 0]
  * @position Start -600 0
- * @position validator -300 0
- * @position transformer 0 0
- * @position outputter 300 0
  * @position Exit 600 0
  * @path Start -> validator -> transformer -> outputter -> Exit
  * @connect validator.onFailure -> Exit.onFailure
@@ -48631,12 +48666,14 @@ function ${name}(${inputPortName}: any): { ${outputPortName}: any } {
   return { ${outputPortName}: ${inputPortName} };
 }`;
   });
-  const nodeAnnotations = nodeNames.map((name, i) => ` * @node step${i} ${name}`).join("\n");
   const spacing = 300;
   const startX = -(nodeNames.length * (spacing / 2) + spacing / 2);
+  const nodeAnnotations = nodeNames.map((name, i) => {
+    const x = startX + (i + 1) * spacing;
+    return ` * @node step${i} ${name} [position: ${x} 0]`;
+  }).join("\n");
   const positionAnnotations = [
     ` * @position Start ${startX} 0`,
-    ...nodeNames.map((_, i) => ` * @position step${i} ${startX + (i + 1) * spacing} 0`),
     ` * @position Exit ${startX + (nodeNames.length + 1) * spacing} 0`
   ].join("\n");
   const pathNodes = ["Start", ...nodeNames.map((_, i) => `step${i}`), "Exit"];
@@ -48799,13 +48836,10 @@ function aggregateResults(
 
 /**
  * @flowWeaver workflow
- * @node iterator forEachItem [size: 300 200]
- * @node processor processItem iterator.processItem
- * @node aggregator aggregateResults
+ * @node iterator forEachItem [size: 300 200] [position: -90 0]
+ * @node processor processItem iterator.processItem [position: 90 0]
+ * @node aggregator aggregateResults [position: 270 0]
  * @position Start -450 0
- * @position iterator -90 0
- * @position processor 90 0
- * @position aggregator 270 0
  * @position Exit 450 0
  * @connect Start.execute -> iterator.execute
  * @connect Start.items -> iterator.items
@@ -48936,13 +48970,10 @@ function handleFailure(
 
 /**
  * @flowWeaver workflow
- * @node router evaluateCondition
- * @node successHandler handleSuccess
- * @node failureHandler handleFailure
+ * @node router evaluateCondition [position: -180 0]
+ * @node successHandler handleSuccess [position: 90 -90]
+ * @node failureHandler handleFailure [position: 90 90]
  * @position Start -450 0
- * @position router -180 0
- * @position successHandler 90 -90
- * @position failureHandler 90 90
  * @position Exit 360 0
  * @connect Start.execute -> router.execute
  * @connect Start.data -> router.data
@@ -49587,13 +49618,10 @@ async function executeTools(
  * AI Agent that uses tools to accomplish tasks
  *
  * @flowWeaver workflow
- * @node loop agentLoop [size: 450 350]
- * @node llm callLLM loop.iteration
- * @node tools executeTools loop.iteration
+ * @node loop agentLoop [size: 450 350] [position: -180 0]
+ * @node llm callLLM loop.iteration [position: -40 100]
+ * @node tools executeTools loop.iteration [position: 120 200]
  * @position Start -450 0
- * @position loop -180 0
- * @position llm -40 100
- * @position tools 120 200
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute
  * @connect Start.userMessage -> loop.userMessage
@@ -49877,13 +49905,10 @@ async function act(
  * ReAct Agent \u2014 iterative Thought\u2192Action\u2192Observation loop
  *
  * @flowWeaver workflow
- * @node loop reactLoop [size: 450 250]
- * @node thinking think loop.step
- * @node acting act loop.step
+ * @node loop reactLoop [size: 450 250] [position: -150 0]
+ * @node thinking think loop.step [position: -80 30]
+ * @node acting act loop.step [position: 130 30]
  * @position Start -400 0
- * @position loop -150 0
- * @position thinking -80 30
- * @position acting 130 30
  * @position Exit 350 0
  * @connect Start.execute -> loop.execute
  * @connect Start.task -> loop.task
@@ -50064,11 +50089,9 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve
- * @node generator generate
+ * @node retriever retrieve [position: -50 0]
+ * @node generator generate [position: 200 0]
  * @position Start -300 0
- * @position retriever -50 0
- * @position generator 200 0
  * @position Exit 400 0
  * @connect Start.execute -> retriever.execute
  * @connect Start.question -> retriever.query
@@ -50227,13 +50250,10 @@ async function chat(
  * Stateful chat with conversation memory
  *
  * @flowWeaver workflow
- * @node mem memory
- * @node respond chat
- * @node saveMem memory
+ * @node mem memory [position: -150 0]
+ * @node respond chat [position: 50 0]
+ * @node saveMem memory [position: 250 0]
  * @position Start -350 0
- * @position mem -150 0
- * @position respond 50 0
- * @position saveMem 250 0
  * @position Exit 450 0
  * @connect Start.execute -> mem.execute
  * @connect Start.conversationId -> mem.conversationId
@@ -50332,13 +50352,10 @@ function combineData(dataA: any, dataB: any): { aggregated: any } {
 
 /**
  * @flowWeaver workflow
- * @node sourceA fetchSourceA
- * @node sourceB fetchSourceB
- * @node combiner combineData
+ * @node sourceA fetchSourceA [position: -180 -90]
+ * @node sourceB fetchSourceB [position: -180 90]
+ * @node combiner combineData [position: 90 0]
  * @position Start -450 0
- * @position sourceA -180 -90
- * @position sourceB -180 90
- * @position combiner 90 0
  * @position Exit 360 0
  * @connect Start.execute -> sourceA.execute
  * @connect Start.execute -> sourceB.execute
@@ -50483,13 +50500,10 @@ function formatResponse(
 
 /**
  * @flowWeaver workflow
- * @node validator validateRequest
- * @node processor processPayload
- * @node responder formatResponse
+ * @node validator validateRequest [position: -180 0]
+ * @node processor processPayload [position: 90 -60]
+ * @node responder formatResponse [position: 270 0]
  * @position Start -450 0
- * @position validator -180 0
- * @position processor 90 -60
- * @position responder 270 0
  * @position Exit 450 0
  * @connect Start.execute -> validator.execute
  * @connect Start.headers -> validator.headers
@@ -50624,11 +50638,9 @@ function tryOperation(
 
 /**
  * @flowWeaver workflow
- * @node loop retryLoop [size: 300 200]
- * @node tryOp tryOperation loop.attempt
+ * @node loop retryLoop [size: 300 200] [position: -90 0]
+ * @node tryOp tryOperation loop.attempt [position: 90 0]
  * @position Start -450 0
- * @position loop -90 0
- * @position tryOp 90 0
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute
  * @connect Start.data -> loop.data
@@ -50956,15 +50968,11 @@ async function respond(
  * @flowWeaver workflow
  * @trigger event="agent/request"
  * @retries 3
- * @node cls classify
- * @node tools executeTool
- * @node approval approvalGate
- * @node resp respond
+ * @node cls classify [position: -280 0]
+ * @node tools executeTool [position: -40 0]
+ * @node approval approvalGate [position: 200 0]
+ * @node resp respond [position: 440 0]
  * @position Start -500 0
- * @position cls -280 0
- * @position tools -40 0
- * @position approval 200 0
- * @position resp 440 0
  * @position Exit 680 0
  * @connect Start.execute -> cls.execute
  * @connect Start.userMessage -> cls.userMessage
@@ -51278,15 +51286,11 @@ async function saveResult(
  * @flowWeaver workflow
  * @trigger event="pipeline/start"
  * @retries 3
- * @node fetch fetchData
- * @node extract extractInfo
- * @node validate validateResult
- * @node save saveResult
+ * @node fetch fetchData [position: -280 0]
+ * @node extract extractInfo [position: -40 0]
+ * @node validate validateResult [position: 200 0]
+ * @node save saveResult [position: 440 0]
  * @position Start -500 0
- * @position fetch -280 0
- * @position extract -40 0
- * @position validate 200 0
- * @position save 440 0
  * @position Exit 680 0
  * @connect Start.execute -> fetch.execute
  * @connect Start.url -> fetch.url
@@ -52766,9 +52770,10 @@ function applyPattern(options) {
       conflicts.push(nodeType.name);
     }
   }
-  const nodeDeclarations = pattern.instances.map(
-    (inst) => ` * @node ${nodePrefix}${inst.id} ${inst.nodeType}`
-  );
+  const nodeDeclarations = pattern.instances.map((inst) => {
+    const posAttr = inst.config?.x !== void 0 && inst.config?.y !== void 0 ? ` [position: ${inst.config.x} ${inst.config.y}]` : "";
+    return ` * @node ${nodePrefix}${inst.id} ${inst.nodeType}${posAttr}`;
+  });
   const connectDeclarations = [];
   const wiringInstructions = [];
   const wiringOperations = [];
@@ -52803,7 +52808,6 @@ function applyPattern(options) {
       );
     }
   }
-  const positionDeclarations = pattern.instances.filter((inst) => inst.config?.x !== void 0 && inst.config?.y !== void 0).map((inst) => ` * @position ${nodePrefix}${inst.id} ${inst.config.x} ${inst.config.y}`);
   const nodeTypesAdded = [];
   const nodeTypeFunctions = [];
   for (const nodeType of pattern.nodeTypes) {
@@ -52815,8 +52819,7 @@ function applyPattern(options) {
   const annotationLines = [
     `// --- Pattern: ${pattern.name} ${prefix ? `(prefix: ${prefix})` : ""} ---`,
     ...nodeDeclarations,
-    ...connectDeclarations,
-    ...positionDeclarations
+    ...connectDeclarations
   ];
   const workflowMatch = targetContent.match(/\/\*\*[\s\S]*?@flowWeaver\s+workflow[\s\S]*?\*\//);
   if (!workflowMatch) {
@@ -52928,7 +52931,8 @@ function extractPattern(options) {
   lines.push(` * @flowWeaver pattern`);
   lines.push(` * @name ${patternName}`);
   for (const inst of extractedInstances) {
-    lines.push(` * @node ${inst.id} ${inst.nodeType}`);
+    const posAttr = inst.config?.x !== void 0 && inst.config?.y !== void 0 ? ` [position: ${inst.config.x} ${inst.config.y}]` : "";
+    lines.push(` * @node ${inst.id} ${inst.nodeType}${posAttr}`);
   }
   for (const conn of internalConnections) {
     lines.push(
@@ -52954,11 +52958,6 @@ function extractPattern(options) {
   for (const port of [...new Set(outputPorts)]) {
     lines.push(` * @port OUT.${port}`);
   }
-  for (const inst of extractedInstances) {
-    if (inst.config?.x !== void 0 && inst.config?.y !== void 0) {
-      lines.push(` * @position ${inst.id} ${inst.config.x} ${inst.config.y}`);
-    }
-  }
   lines.push(" */");
   lines.push("function patternPlaceholder() {}");
   for (const nodeType of usedNodeTypes) {
@@ -95128,7 +95127,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.7.0" : "0.0.0-dev";
+var version2 = true ? "0.8.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

package/dist/cli/templates/workflows/aggregator.js

@@ -68,13 +68,10 @@ function combineData(dataA: any, dataB: any): { aggregated: any } {
 
 /**
  * @flowWeaver workflow
- * @node sourceA fetchSourceA
- * @node sourceB fetchSourceB
- * @node combiner combineData
+ * @node sourceA fetchSourceA [position: -180 -90]
+ * @node sourceB fetchSourceB [position: -180 90]
+ * @node combiner combineData [position: 90 0]
  * @position Start -450 0
- * @position sourceA -180 -90
- * @position sourceB -180 90
- * @position combiner 90 0
  * @position Exit 360 0
  * @connect Start.execute -> sourceA.execute
  * @connect Start.execute -> sourceB.execute

package/dist/cli/templates/workflows/ai-agent-durable.js

@@ -294,15 +294,11 @@ async function respond(
  * @flowWeaver workflow
  * @trigger event="agent/request"
  * @retries 3
- * @node cls classify
- * @node tools executeTool
- * @node approval approvalGate
- * @node resp respond
+ * @node cls classify [position: -280 0]
+ * @node tools executeTool [position: -40 0]
+ * @node approval approvalGate [position: 200 0]
+ * @node resp respond [position: 440 0]
  * @position Start -500 0
- * @position cls -280 0
- * @position tools -40 0
- * @position approval 200 0
- * @position resp 440 0
  * @position Exit 680 0
  * @connect Start.execute -> cls.execute
  * @connect Start.userMessage -> cls.userMessage

package/dist/cli/templates/workflows/ai-agent.js

@@ -283,13 +283,10 @@ async function executeTools(
  * AI Agent that uses tools to accomplish tasks
  *
  * @flowWeaver workflow
- * @node loop agentLoop [size: 450 350]
- * @node llm callLLM loop.iteration
- * @node tools executeTools loop.iteration
+ * @node loop agentLoop [size: 450 350] [position: -180 0]
+ * @node llm callLLM loop.iteration [position: -40 100]
+ * @node tools executeTools loop.iteration [position: 120 200]
  * @position Start -450 0
- * @position loop -180 0
- * @position llm -40 100
- * @position tools 120 200
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute
  * @connect Start.userMessage -> loop.userMessage

package/dist/cli/templates/workflows/ai-chat.js

@@ -127,13 +127,10 @@ async function chat(
  * Stateful chat with conversation memory
  *
  * @flowWeaver workflow
- * @node mem memory
- * @node respond chat
- * @node saveMem memory
+ * @node mem memory [position: -150 0]
+ * @node respond chat [position: 50 0]
+ * @node saveMem memory [position: 250 0]
  * @position Start -350 0
- * @position mem -150 0
- * @position respond 50 0
- * @position saveMem 250 0
  * @position Exit 450 0
  * @connect Start.execute -> mem.execute
  * @connect Start.conversationId -> mem.conversationId

package/dist/cli/templates/workflows/ai-pipeline-durable.js

@@ -282,15 +282,11 @@ async function saveResult(
  * @flowWeaver workflow
  * @trigger event="pipeline/start"
  * @retries 3
- * @node fetch fetchData
- * @node extract extractInfo
- * @node validate validateResult
- * @node save saveResult
+ * @node fetch fetchData [position: -280 0]
+ * @node extract extractInfo [position: -40 0]
+ * @node validate validateResult [position: 200 0]
+ * @node save saveResult [position: 440 0]
  * @position Start -500 0
- * @position fetch -280 0
- * @position extract -40 0
- * @position validate 200 0
- * @position save 440 0
  * @position Exit 680 0
  * @connect Start.execute -> fetch.execute
  * @connect Start.url -> fetch.url

package/dist/cli/templates/workflows/ai-rag.js

@@ -145,11 +145,9 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve
- * @node generator generate
+ * @node retriever retrieve [position: -50 0]
+ * @node generator generate [position: 200 0]
  * @position Start -300 0
- * @position retriever -50 0
- * @position generator 200 0
  * @position Exit 400 0
  * @connect Start.execute -> retriever.execute
  * @connect Start.question -> retriever.query

package/dist/cli/templates/workflows/ai-react.js

@@ -247,13 +247,10 @@ async function act(
  * ReAct Agent — iterative Thought→Action→Observation loop
  *
  * @flowWeaver workflow
- * @node loop reactLoop [size: 450 250]
- * @node thinking think loop.step
- * @node acting act loop.step
+ * @node loop reactLoop [size: 450 250] [position: -150 0]
+ * @node thinking think loop.step [position: -80 30]
+ * @node acting act loop.step [position: 130 30]
  * @position Start -400 0
- * @position loop -150 0
- * @position thinking -80 30
- * @position acting 130 30
  * @position Exit 350 0
  * @connect Start.execute -> loop.execute
  * @connect Start.task -> loop.task

package/dist/cli/templates/workflows/conditional.js

@@ -105,13 +105,10 @@ function handleFailure(
 
 /**
  * @flowWeaver workflow
- * @node router evaluateCondition
- * @node successHandler handleSuccess
- * @node failureHandler handleFailure
+ * @node router evaluateCondition [position: -180 0]
+ * @node successHandler handleSuccess [position: 90 -90]
+ * @node failureHandler handleFailure [position: 90 90]
  * @position Start -450 0
- * @position router -180 0
- * @position successHandler 90 -90
- * @position failureHandler 90 90
  * @position Exit 360 0
  * @connect Start.execute -> router.execute
  * @connect Start.data -> router.data

package/dist/cli/templates/workflows/error-handler.js

@@ -105,11 +105,9 @@ function tryOperation(
 
 /**
  * @flowWeaver workflow
- * @node loop retryLoop [size: 300 200]
- * @node tryOp tryOperation loop.attempt
+ * @node loop retryLoop [size: 300 200] [position: -90 0]
+ * @node tryOp tryOperation loop.attempt [position: 90 0]
  * @position Start -450 0
- * @position loop -90 0
- * @position tryOp 90 0
  * @position Exit 360 0
  * @connect Start.execute -> loop.execute
  * @connect Start.data -> loop.data

package/dist/cli/templates/workflows/foreach.js

@@ -101,13 +101,10 @@ function aggregateResults(
 
 /**
  * @flowWeaver workflow
- * @node iterator forEachItem [size: 300 200]
- * @node processor processItem iterator.processItem
- * @node aggregator aggregateResults
+ * @node iterator forEachItem [size: 300 200] [position: -90 0]
+ * @node processor processItem iterator.processItem [position: 90 0]
+ * @node aggregator aggregateResults [position: 270 0]
  * @position Start -450 0
- * @position iterator -90 0
- * @position processor 90 0
- * @position aggregator 270 0
  * @position Exit 450 0
  * @connect Start.execute -> iterator.execute
  * @connect Start.items -> iterator.items