Skip to content

docs(uipath-maestro-flow): drop the format step now that compile lays out (SDK 6.113.0) - #4723

Merged
tmatup merged 5 commits into
mainfrom
docs/flow-compile-autolayout
Nov 15, 2026
Merged

tmatup merged 5 commits into
mainfrom
docs/flow-compile-autolayout

Conversation

@tmatup

@tmatup tmatup commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

The SDK change shipped: UiPath/builder-sdk#2035 is in @uipath/maestro-builder-sdk 6.113.0, and the docs name that version as the floor.

Short version

compile now lays out a flow with no .layout() exactly as uip maestro flow format does, and gives every node its canvas-shape size (UiPath/builder-sdk#2035). So the skill no longer needs to tell agents to run format after compile, or to hand-size agent nodes with dim(288, 96).

Example: at(1312, 144) on an inline agent now compiles to 288 x 96; before, it compiled to 96 x 96 unless written at(1312, 144, dim(288, 96)).

What text is retired, and why

  • SKILL.md Lifecycle: the "Greenfield only ... flow format" step after compile. format on a compiled file now moves nothing.
  • references/CLI-LOOP.md: the paragraph saying to run format on a greenfield file before upload/debug/designer.
  • references/operate.md "Lay out the emitted flow first" (renamed Layout of the emitted flow): replaced the format instruction and the "one flat placeholder row" explanation with what compile now does (positions as format, sizes: container 560 x 320, agent 288 x 96, else 96 x 96). Kept "never format a merged brownfield file": format still discards author positions.
  • operate.md .layout() rules: dropped hand dim(288, 96) for agents and dim() for default-size containers; a container bigger than 560 x 320 still needs dim(). Rule 3 (name every node or none) stays: a partial .layout() still leaves unnamed nodes on compile's placeholder row.
  • references/diagnose.md "Misshapen nodes": removed the format fix and the "agent without dim(288, 96)" cause.
  • extract-document-node.md: two anchor links updated for the renamed heading.

Flavor overrides

skill-flavors/studioweb/uipath-maestro-flow/ overrides for the changed blocks (sdk-lifecycle, local-gates, operate-format, misshapen-format) updated the same way: the new-flow loop drops format; "never format a merged file" stays. Studio Web needs its SDK copy at the release that ships #2035.

Checks run

npm run skills:validate, npm run skills:check-links, npm run skills:build, git diff --check.

🤖 Generated with Claude Code
Co-Authored-By: Claude

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @tmatup's task in 1m 8s —— View job


Summary

The PR removes the uip maestro flow format step after compile and the hand-written dim(288, 96) on agent nodes, because compile now lays out the flow and sizes every node itself (builder-sdk#2035). It changes the canonical uipath-maestro-flow files and the matching Studio Web overrides. "Never format a merged or .layout() file" stays.

Change-by-Change Review

1. skills/uipath-maestro-flow/references/operate.md — no version gate on compile's new layout

Medium

Since this PR, the skill says without condition that compile lays out the flow (L16-24) and that format "moves nothing; skip it". The behaviour only exists from the SDK release that ships #2035. SKILL.md says the uip maestro flow commands hand their semantics to the installed @uipath/maestro-builder-sdk. So an agent on an older global or workspace copy would compile a flat placeholder row and never run format. Nothing would catch it: validate passes, and the diagnose entry now says a no-.layout() source "is not the cause".

The file already gates at/dim this way (layout-sdk-version, rule 5: "need 6.36.0 or later … upgrade that copy"). The same gate fits here:

  • Name the minimum SDK version for compile's layout, with the same check (dist/api-index.md or a version check) and the same upgrade path.
  • Keep a fallback for older copies: run format once on a greenfield file. Since format now moves nothing on a new compile, its NodesRepositioned count also shows whether the installed SDK is the old one.

Without the version, the merge-ordering note in the PR body is the only safeguard, and agents never see it. Fix this →

2. skills/uipath-maestro-flow/references/diagnose.md L121-129 — misshapen-nodes entry

Medium (same root cause as #1)

"A source with no .layout() is not the cause" is only true on a new enough SDK. On an older copy, a no-.layout() source is exactly what produces the old one-row symptom, and the entry has removed the fix for it. Add a sentence: on an SDK older than X, run format once on a greenfield file. The same applies to the Studio Web override (misshapen-format).

3. operate.md .layout() rules 1–3 and the example

OK

The arithmetic checks out:

  • dim(192 × bodyNodes + 192, 320) "from two body nodes on" gives 576 for two nodes. That is larger than 560 and matches eachInvoice: dim(576, 320).
  • One node gives 384, so the default 560 × 320 holds it.

Rule 3 (name every node or none) and rule 4 (never format a .layout() file) still hold.

4. operate.md L34-38 — nodes create without --position, then format

OK

This is still correct. It covers CLI or hand edits, not compile, so it should stay.

5. SKILL.md, CLI-LOOP.md (canonical and Studio Web)

OK

The lifecycle block loses the greenfield format line. CLI-LOOP.md keeps the warning against formatting merged and .layout() files. Both read consistently with operate.md.

6. Anchor rename #lay-out-the-emitted-flow-first → #layout-of-the-emitted-flow

OK

No old anchors are left in skills/ or skill-flavors/ (searched with grep). The new heading ## Layout of the emitted flow produces the anchor the links use.

7. Studio Web overrides

OK

All four touched blocks (sdk-lifecycle, local-gates, operate-format, misshapen-format) match the canonical change. The rule against formatting a merged file is kept. One nit: in the operate-format override, the line "…canvas-shape size: a container (a loop, for example) 560 × 320, an" is much longer than its neighbours. That's cosmetic.

8. Duplication

Low

The sentence "compile lays it out the way format does and gives every node its canvas size" now appears in CLI-LOOP.md, diagnose.md and operate.md. In CLI-LOOP.md and diagnose.md it sits next to a link to operate.md, so it reads as one bridging sentence. That's acceptable, but if the version gate from #1 is added, put it only in operate.md and link to it from the other two.

What's Missing

  • A minimum SDK version, plus a fallback for older SDKs, for compile's built-in layout (feat(EvalsBreakdown): break down eval skill #1, feat: new coded agent skills #2).
  • No test task covers "compile output is already laid out". An optional run_command check that format reports 0 NodesRepositioned on a freshly compiled greenfield flow would lock in the new contract. No existing tests/tasks/uipath-maestro-flow task checks for a flow format command, so nothing regresses.
  • skills/uipath-agents/references/coded/quickstart.md:337 still runs flow format. That flow is edited by hand in JSON, not compiled, so it is still correct and not in this PR's scope.

Area Ratings

Area Status Notes
Frontmatter OK Unchanged
E2E Tests OK No task depends on the removed step; a coverage check is optional
Skill Body OK One lifecycle line removed
References & Assets Issue No SDK version gate for compile's layout (#1, #2)
Repo Hygiene OK Scoped to one skill and its overrides; no secrets or personal paths

Issues for Manual Review

Conclusion

The change is correct for the target SDK and well scoped. Before merge I'd ask for one change: name the minimum SDK version for compile's layout and keep the format fallback for older SDKs (#1/#2). Without it, an agent on an older SDK silently ships flat-row layouts.

@tmatup

tmatup commented Nov 14, 2026

Copy link
Copy Markdown
Member Author

Review triage (Claude bot):

  • feat(EvalsBreakdown): break down eval skill #1 / feat: new coded agent skills #2 version gate (Medium): fixed in 0a8b667. operate.md now says compile layout needs an SDK with builder-sdk#2035 and gives the older-SDK fallback once: an older SDK writes every node 96 x 96 on one row at y = 144; then run format once on a greenfield file and give agents dim(288, 96) / containers dim(560, 320) in a .layout(). Upgrade text is a new compile-layout-sdk-upgrade flavor block (Studio Web: "tell the user: Studio Web owns the SDK copy"). diagnose.md (canonical and Studio Web) names the exception and links to operate.md instead of repeating it, as feat(CodedAgents): llm and interruption patterns #8 suggested. The gate cites the SDK PR because the release version is not cut yet; it can be replaced with the version number at merge time.
  • chore: compact skills #7 long line nit: fixed.
  • Manual review items: sizes come straight from builder-sdk#2035 auto-layout.ts (container 560 x 320, rectangle 288 x 96, else 96 x 96, read from the node's display.shape). A partial .layout() keeps the placeholder row for unnamed nodes (fix(skills): route diagnostic intent to uipath-troubleshoot before platform work (cherry-pick #1980 to v1.197) #2035 body: "A scope with a .layout() keeps today's behaviour for the nodes it leaves out"), so rule 3 stands.
  • Test task / quickstart.md: out of scope for this retirement PR, as the review notes.

🤖 Generated with Claude Code
Co-Authored-By: Claude

@tmatup
tmatup force-pushed the docs/flow-compile-autolayout branch from 0a8b667 to d46aca1 Compare November 15, 2026 00:27
tmatup added a commit that referenced this pull request Nov 15, 2026
…eep the grid caveat for an older SDK

Replayed onto the rebased #4723: drops the placeholder-grid warning for at()
in brownfield (builder-sdk#2036), with the older-SDK fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)

@rockymadden rockymadden left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Commented: 1 blocker. The Studio Web new-flow loop still compiles a flat row, and this PR removes its format.

What

Docs for builder-sdk#2035 (still open, latest review is changes requested). compile now lays out a source with no .layout() as format does, and sizes nodes by shape. The PR drops the post-compile format step and the hand dim(288, 96) from the canonical skill and the Studio Web flavor, and keeps "never format a merged file".

Axes

Axis Blockers Non-blockers Top finding
Correctness & logic 1 0 Studio Web new flow keeps the placeholder row skill-flavors/studioweb/uipath-maestro-flow/SKILL.md:98
Code quality & simplicity 0 1 lines that change nothing skills/uipath-maestro-flow/references/operate.md:18
Types & contracts 0 0 none
Tests & validation 0 1 no eval checks a greenfield compile lands laid out
Security 0 0 none
Architecture & design 0 0 none
Error handling & resilience 0 0 none
Interface, docs & compatibility 0 1 SDK gate names a PR, not a version skills/uipath-maestro-flow/references/operate.md:33

Overall findings

  • 🟡 non-blocker · Tests & validation: no coder eval task checks that a greenfield compile lands laid out without format. A Studio Web case starting from a decompiled new.flow would have caught the blocker. Fix: add one advisory task that greps the compiled .flow for distinct y values.

Verified vs reasoned

  • ✅ Checked against builder-sdk#2035 head 445a83af: shape sizes (container 560 × 320, rectangle 288 × 96, else 96 × 96), origin (256, 144). All three agent types (uipath.agent.autonomous, .conversational, .voice) use rectangle. A scope with any author entry keeps the placeholder row.
  • ✅ Grep found no leftover lay-out-the-emitted-flow-first anchor, dim(288 rule, or post-compile format step. operate.md:43-46 (nodes create without --position, then format) is a separate CLI path and stays valid.
  • ✅ Every canonical change sits inside a flavor block that the Studio Web override replaces, or is inherited text that reads correctly with the override's wording.
  • ❓ Not verified: the Studio Web canvas's new.flow (trigger position). That is why the blocker is reasoned.
  • ❓ #2035's last two fixes (flagging every compiled node ui.placeholder: true) have not been re-reviewed. Recheck these docs if that thread changes behavior again.

tl;dr

The canonical docs match the SDK. In Studio Web a new flow starts from a decompiled new.flow, so its trigger entry turns off auto-layout and the flow compiles flat. This PR removes the format that fixed that.

… out

compile now lays out a flow or subflow with no .layout() the way
`uip maestro flow format` does, and sizes every node by its canvas shape
(UiPath/builder-sdk#2035). Retire the "run format on greenfield" step, the
hand dim(288, 96) for agents, and dim() for default-size containers.
Keep "never format a merged brownfield file". Studio Web overrides updated
to match.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
Address review: state that compile layout needs an SDK with
builder-sdk#2035, and keep the format / dim() fallback for an older SDK,
with an upgrade flavor block (Studio Web: tell the user).

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
…ly .layout() before compile

Review on #4723: the Studio Web new-flow loop starts from a decompiled
new.flow, whose .layout() names the canvas trigger, so compile kept every
added step on the placeholder row. The loop and the operate-format
override now say to delete that call first. Also trims two operate.md
lines that changed nothing.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup
tmatup force-pushed the docs/flow-compile-autolayout branch from d46aca1 to f57a2c3 Compare November 15, 2026 16:55
tmatup added a commit that referenced this pull request Nov 15, 2026
…eep the grid caveat for an older SDK

Replayed onto the rebased #4723 (builder-sdk#2036), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)

@rockymadden rockymadden left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recommendation: 🟢 Approved. The blocker and one non-blocker are fixed at f57a2c30; two non-blockers stand.

Fixed

  • ✅ 🔴 Studio Web new flow compiled flat: the loop now deletes the decompiled new.flow's trigger-only .layout() before compile (skill-flavors/studioweb/uipath-maestro-flow/SKILL.md:96), and the operate-format override says why. Matches builder-sdk#2035/#2036: a scope with any entry keeps the placeholder row.
  • ✅ 🟡 Sentences that changed nothing in operate.md: dropped; what's left ends in "skip it".

Still open

  • 🟡 PR-number gate: operate.md:31, diagnose.md:127 and the flavor's diagnose.md:35 say "builder-sdk#2035". Inline.
  • 🟡 Overall · Tests & validation: no eval checks that a greenfield compile lands laid out without format. Fix: one advisory task that checks the compiled .flow has more than one distinct y.

New: none. The new compile-layout-sdk-upgrade block has its Studio Web override, so no flavor drift.

Axes

Axis Blockers Non-blockers Top finding
Correctness & logic 0 0 none
Code quality & simplicity 0 0 none
Types & contracts 0 0 none
Tests & validation 0 1 no eval for greenfield layout
Security 0 0 none
Architecture & design 0 0 none
Error handling & resilience 0 0 none
Interface, docs & compatibility 0 1 PR-number SDK gate skills/uipath-maestro-flow/references/operate.md:31

Not verified: a real Studio Web new.flow; I read the SDK heads, didn't run anything.

tl;dr

  • Blocker fixed. Swap the PR number for the release version when #2035 ships, then merge.

…de its size budget

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
tmatup added a commit that referenced this pull request Nov 15, 2026
…eep the grid caveat for an older SDK

Replayed onto the rebased #4723 (builder-sdk#2036), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
… output (6.113.0)

builder-sdk#2035 shipped in @uipath/maestro-builder-sdk 6.113.0, so the
gates name that version instead of the PR. The Studio Web override tells
the user the version rather than installing it.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
tmatup added a commit that referenced this pull request Nov 15, 2026
…eep the grid caveat for an older SDK

Replayed onto the rebased #4723 (builder-sdk#2036), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
@tmatup tmatup changed the title docs(uipath-maestro-flow): drop the format step now that compile lays out (merge after the SDK release that ships builder-sdk#2035) docs(uipath-maestro-flow): drop the format step now that compile lays out (SDK 6.113.0) Nov 15, 2026
@tmatup
tmatup merged commit ff55986 into main Nov 15, 2026
50 checks passed
@tmatup
tmatup deleted the docs/flow-compile-autolayout branch November 15, 2026 23:20
tmatup added a commit that referenced this pull request Nov 15, 2026
…eep the grid caveat for an older SDK

Replayed onto the rebased #4723 (builder-sdk#2036), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
tmatup added a commit that referenced this pull request Nov 15, 2026
… (SDK 6.114.0) (#4724)

* docs(uipath-maestro-flow): merge places only nodes compile flagged; keep the grid caveat for an older SDK

Replayed onto the rebased #4723 (builder-sdk#2036), with the older-SDK
fallback.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)

* docs(uipath-maestro-flow): name the SDK release that marks compile-placed nodes (6.114.0)

builder-sdk#2036 shipped in @uipath/maestro-builder-sdk 6.114.0. The Studio
Web override tells the user the version.

🤖 Generated with Claude Code
Co-Authored-By: [Claude](mailto:noreply@anthropic.com)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants