fix(maestro-flow): align full eval corpus across authoring loops

.github/workflows/run-coder-eval.yml

@@ -320,8 +320,9 @@ jobs:
           echo "${{ secrets.GH_PACKAGES_TOKEN || secrets.GH_PAT }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
           docker pull "ghcr.io/uipath/coder-eval-agent:${CE_IMAGE_TAG}"
 
-      # Build the skills extension image (`@uipath/cli` + `@uipath/admin-tool`
-      # on top of coder-eval-agent). Matches smoke-skills.yml + daily.sh.
+      # Build the skills extension image (`@uipath/cli`, its tool plugins, and
+      # `@uipath/flow-sdk` on top of coder-eval-agent). Matches
+      # smoke-skills.yml + daily.sh.
       - name: Build skills Docker image
         env:
           DOCKER_BUILDKIT: "1"
@@ -332,6 +333,7 @@ jobs:
             --build-arg CODER_EVAL_IMAGE="ghcr.io/uipath/coder-eval-agent:${CE_IMAGE_TAG}" \
             --secret id=npm_auth_token,env=NPM_AUTH_TOKEN \
             --build-arg CLI_VERSION="${{ inputs.cli_version }}" \
+            --build-arg FLOW_SDK_VERSION="${{ vars.FLOW_SDK_VERSION || 'latest' }}" \
             -t skills-image:latest \
             -f tests/docker/Dockerfile \
             .

.github/workflows/smoke-skills.yml

@@ -368,12 +368,13 @@ jobs:
           echo "${{ secrets.GH_PACKAGES_TOKEN || secrets.GH_PAT }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
           docker pull ghcr.io/uipath/coder-eval-agent:${{ steps.ceref.outputs.version }}
 
-      # Build custom smoke image extending coder-eval-agent with @uipath/cli and
-      # every whitelisted tool plugin from GitHub Packages @dev (see
-      # tests/docker/Dockerfile). Every push to `cli/main` publishes a
-      # `-dev.<run>` prerelease under the `dev` dist-tag (cli PR #2650 renamed the
-      # old `alpha` tag → `dev` on 2026-06-26), so smoke tracks main — not stale
-      # `latest` from public npm (which lags by ~2 weeks).
+      # Build custom smoke image extending coder-eval-agent with @uipath/cli,
+      # every whitelisted tool plugin from GitHub Packages @dev, and the latest
+      # published @uipath/flow-sdk (see tests/docker/Dockerfile). Every push to
+      # `cli/main` publishes a `-dev.<run>` prerelease under the `dev` dist-tag
+      # (cli PR #2650 renamed the old `alpha` tag → `dev` on 2026-06-26), so
+      # smoke tracks main — not stale `latest` from public npm (which lags by ~2
+      # weeks).
       - name: Build skills smoke Docker image
         env:
           DOCKER_BUILDKIT: "1"
@@ -382,6 +383,7 @@ jobs:
           docker build \
             --build-arg CODER_EVAL_IMAGE=ghcr.io/uipath/coder-eval-agent:${{ steps.ceref.outputs.version }} \
             --secret id=npm_auth_token,env=NPM_AUTH_TOKEN \
+            --build-arg FLOW_SDK_VERSION="${{ vars.FLOW_SDK_VERSION || 'latest' }}" \
             -t skills-image:latest \
             -f tests/docker/Dockerfile \
             .

.github/workflows/sync-maestro-sdk-preview.yml

@@ -80,7 +80,7 @@ jobs:
           for skill in flow case bpmn; do
             findings="$RUNNER_TEMP/maestro-$skill-verbs.ndjson"
             python3 scripts/check-skill-verbs.py \
-              --json "preview/uipath-maestro-$skill" > "$findings"
+              --json "preview/skills/uipath-maestro-$skill" > "$findings"
             blocking=$(jq -c \
               'select(.severity=="Stale" and .matched_prefix == null)' \
               "$findings" | wc -l | tr -d ' ')
@@ -108,16 +108,16 @@ jobs:
         run: |
           set -euo pipefail
           if git diff --quiet -- \
-            preview/uipath-maestro-flow \
-            preview/uipath-maestro-case \
-            preview/uipath-maestro-bpmn; then
+            preview/skills/uipath-maestro-flow \
+            preview/skills/uipath-maestro-case \
+            preview/skills/uipath-maestro-bpmn; then
             changed=false
           else
             changed=true
             git diff --stat -- \
-              preview/uipath-maestro-flow \
-              preview/uipath-maestro-case \
-              preview/uipath-maestro-bpmn
+              preview/skills/uipath-maestro-flow \
+              preview/skills/uipath-maestro-case \
+              preview/skills/uipath-maestro-bpmn
           fi
           if [ "$changed" != "$SCRIPT_CHANGED" ]; then
             echo "Sync script reported changed=$SCRIPT_CHANGED but git reported changed=$changed."
@@ -146,9 +146,9 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git checkout -b "$BRANCH"
           git add \
-            preview/uipath-maestro-flow \
-            preview/uipath-maestro-case \
-            preview/uipath-maestro-bpmn
+            preview/skills/uipath-maestro-flow \
+            preview/skills/uipath-maestro-case \
+            preview/skills/uipath-maestro-bpmn
           git commit \
             -m "chore(preview): re-sync Maestro SDK skills to flow-builder-sdk@$NEW_PIN" \
             -m "🤖 Generated with Claude Code

.github/workflows/test-helpers.yml

@@ -5,6 +5,8 @@ on:
     paths:
       - 'tests/tasks/uipath-maestro-flow/**'
       - 'tests/tasks/uipath-maestro-case/**'
+      - 'tests/tasks/uipath-maestro-bpmn/**'
+      - 'skills/uipath-maestro-bpmn/validator/bpmn-spec.json'
       - 'tests/tasks/uipath-planner/**'
       - 'tests/tasks/uipath-agents/**'
       - 'tests/tasks/uipath-admin/**'
@@ -15,6 +17,22 @@ on:
   workflow_dispatch:
 
 jobs:
+  pytest-bpmn-check:
+    runs-on: uipath-ubuntu-latest
+    name: maestro-bpmn checker unit tests
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4.4.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
+        with:
+          python-version: '3.13'
+
+      - name: Install pytest
+        run: pip install pytest
+
+      - name: Run pytest
+        run: pytest tests/tasks/uipath-maestro-bpmn/ -v
+
   pytest-flow-check:
     runs-on: uipath-ubuntu-latest
     name: maestro-flow checker unit tests

.github/workflows/verb-gate.yml

@@ -49,11 +49,11 @@ jobs:
           # verbs exactly like `skills/` ones, and a retired verb rots the same
           # way in either place.
           if echo "$CHANGED" | grep -qE '^(assets/uip-catalog-snapshot\.json|scripts/check-skill-verbs\.py|\.github/workflows/verb-gate\.yml)$'; then
-            SKILLS=$(ls -d skills/*/ preview/*/ 2>/dev/null | sed 's|/$||' | sort -u)
+            SKILLS=$(ls -d skills/*/ preview/skills/*/ 2>/dev/null | sed 's|/$||' | sort -u)
           else
             SKILLS=$(echo "$CHANGED" \
-              | grep -E '^(skills|preview)/[^/]+/.*\.md$' \
-              | sed -E 's#^((skills|preview)/[^/]+)/.*#\1#' \
+              | grep -E '^(skills|preview/skills)/[^/]+/.*\.md$' \
+              | sed -E 's#^((skills|preview/skills)/[^/]+)/.*#\1#' \
               | sort -u || true)
           fi
 

CODEOWNERS

@@ -18,9 +18,9 @@
 /skill-flavors/studioweb/ @astridstaicu
 
 # preview skills
-/preview/uipath-maestro-flow/ @UiPath/maestro-cli-team
-/preview/uipath-maestro-case/ @UiPath/maestro-cli-team
-/preview/uipath-maestro-bpmn/ @UiPath/maestro-cli-team
+/preview/skills/uipath-maestro-flow/ @UiPath/maestro-cli-team
+/preview/skills/uipath-maestro-case/ @dmetzgar @tmatup
+/preview/skills/uipath-maestro-bpmn/ @UiPath/maestro-cli-team
 
 # Activity references (bundled inside uipath-rpa skill)
 /skills/uipath-rpa/references/activity-docs/ @DragosUnguru

preview/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "uipath-preview",
+  "version": "0.1.0",
+  "description": "UiPath Maestro preview skills — the builder-SDK authoring path for uipath-maestro-{flow,case,bpmn}. Synced from UiPath/flow-builder-sdk by scripts/sync-maestro-sdk-preview.mjs; loads as a Claude Code plugin root (skills/<name>/SKILL.md).",
+  "author": { "name": "UiPath" },
+  "license": "MIT",
+  "homepage": "https://github.com/UiPath/skills",
+  "repository": "https://github.com/UiPath/skills"
+}

scripts/sync-maestro-sdk-preview.mjs

@@ -13,31 +13,31 @@ const sourceRoot = 'typescript/sdk';
 const skillMappings = [
   {
     source: `${sourceRoot}/skill/SKILL.md`,
-    target: 'preview/uipath-maestro-flow/SKILL.md',
+    target: 'preview/skills/uipath-maestro-flow/SKILL.md',
   },
   {
     source: `${sourceRoot}/skill/SKILL-case.md`,
-    target: 'preview/uipath-maestro-case/SKILL.md',
+    target: 'preview/skills/uipath-maestro-case/SKILL.md',
   },
   {
     source: `${sourceRoot}/skill/SKILL-bpmn.md`,
-    target: 'preview/uipath-maestro-bpmn/SKILL.md',
+    target: 'preview/skills/uipath-maestro-bpmn/SKILL.md',
   },
 ];
 
 const provenanceFiles = [
-  ['preview/uipath-maestro-flow/SKILL.md', 'typescript/sdk/skill/SKILL.md'],
-  ['preview/uipath-maestro-case/SKILL.md', 'typescript/sdk/skill/SKILL-case.md'],
-  ['preview/uipath-maestro-bpmn/SKILL.md', 'typescript/sdk/skill/SKILL-bpmn.md'],
+  ['preview/skills/uipath-maestro-flow/SKILL.md', 'typescript/sdk/skill/SKILL.md'],
+  ['preview/skills/uipath-maestro-case/SKILL.md', 'typescript/sdk/skill/SKILL-case.md'],
+  ['preview/skills/uipath-maestro-bpmn/SKILL.md', 'typescript/sdk/skill/SKILL-bpmn.md'],
 ];
 
 const managedDirectories = [
-  'preview/uipath-maestro-flow/references',
-  'preview/uipath-maestro-flow/examples',
-  'preview/uipath-maestro-case/references',
-  'preview/uipath-maestro-case/examples',
-  'preview/uipath-maestro-bpmn/references',
-  'preview/uipath-maestro-bpmn/examples',
+  'preview/skills/uipath-maestro-flow/references',
+  'preview/skills/uipath-maestro-flow/examples',
+  'preview/skills/uipath-maestro-case/references',
+  'preview/skills/uipath-maestro-case/examples',
+  'preview/skills/uipath-maestro-bpmn/references',
+  'preview/skills/uipath-maestro-bpmn/examples',
 ];
 
 const oldSiblingParagraph = [
@@ -190,40 +190,40 @@ function collectMappings(upstreamRoot, refs) {
         'bpmn-runtime.md',
       ].includes(name)) continue;
       const relative = path.posix.relative(referencesRoot, source);
-      add(source, `preview/uipath-maestro-flow/references/${relative}`);
+      add(source, `preview/skills/uipath-maestro-flow/references/${relative}`);
     }
 
     const flowExamplesRoot = `${sourceRoot}/example-eval`;
     for (const source of gitFiles(upstreamRoot, ref, flowExamplesRoot)) {
       const relative = path.posix.relative(flowExamplesRoot, source);
-      add(source, `preview/uipath-maestro-flow/examples/${relative}`);
+      add(source, `preview/skills/uipath-maestro-flow/examples/${relative}`);
     }
 
     const sharedExamplesRoot = `${sourceRoot}/example`;
     for (const source of gitFiles(upstreamRoot, ref, sharedExamplesRoot)) {
       const name = path.posix.basename(source);
       const relative = path.posix.relative(sharedExamplesRoot, source);
       if (name.endsWith('.case.ts')) {
-        add(source, `preview/uipath-maestro-case/examples/${relative}`);
+        add(source, `preview/skills/uipath-maestro-case/examples/${relative}`);
       } else if (relative === 'case-bindings.json') {
-        add(source, 'preview/uipath-maestro-case/examples/bindings.json');
+        add(source, 'preview/skills/uipath-maestro-case/examples/bindings.json');
       } else if (name.endsWith('.bpmn.ts')) {
-        add(source, `preview/uipath-maestro-bpmn/examples/${relative}`);
+        add(source, `preview/skills/uipath-maestro-bpmn/examples/${relative}`);
       }
     }
   }
 
   add(
     `${sourceRoot}/skill/references/case-api.md`,
-    'preview/uipath-maestro-case/references/api.md',
+    'preview/skills/uipath-maestro-case/references/api.md',
   );
   add(
     `${sourceRoot}/skill/references/bpmn-api.md`,
-    'preview/uipath-maestro-bpmn/references/api.md',
+    'preview/skills/uipath-maestro-bpmn/references/api.md',
   );
   for (const [source, target] of [
-    [`${sourceRoot}/skill/references/case-runtime.md`, 'preview/uipath-maestro-case/references/case-runtime.md'],
-    [`${sourceRoot}/skill/references/bpmn-runtime.md`, 'preview/uipath-maestro-bpmn/references/bpmn-runtime.md'],
+    [`${sourceRoot}/skill/references/case-runtime.md`, 'preview/skills/uipath-maestro-case/references/case-runtime.md'],
+    [`${sourceRoot}/skill/references/bpmn-runtime.md`, 'preview/skills/uipath-maestro-bpmn/references/bpmn-runtime.md'],
   ]) {
     if (refs.some((ref) => gitObjectExists(upstreamRoot, ref, source))) add(source, target);
   }
@@ -406,13 +406,13 @@ function adaptBpmnRuntime(text) {
 }
 
 const snapshotAdaptations = new Map([
-  ['preview/uipath-maestro-flow/SKILL.md', adaptFlowSkill],
-  ['preview/uipath-maestro-case/SKILL.md', adaptCaseSkill],
-  ['preview/uipath-maestro-bpmn/SKILL.md', adaptBpmnSkill],
-  ['preview/uipath-maestro-flow/references/api.md', adaptFlowApi],
-  ['preview/uipath-maestro-case/examples/NotifyOnApproval.case.ts', adaptCaseExample],
-  ['preview/uipath-maestro-case/references/case-runtime.md', adaptCaseRuntime],
-  ['preview/uipath-maestro-bpmn/references/bpmn-runtime.md', adaptBpmnRuntime],
+  ['preview/skills/uipath-maestro-flow/SKILL.md', adaptFlowSkill],
+  ['preview/skills/uipath-maestro-case/SKILL.md', adaptCaseSkill],
+  ['preview/skills/uipath-maestro-bpmn/SKILL.md', adaptBpmnSkill],
+  ['preview/skills/uipath-maestro-flow/references/api.md', adaptFlowApi],
+  ['preview/skills/uipath-maestro-case/examples/NotifyOnApproval.case.ts', adaptCaseExample],
+  ['preview/skills/uipath-maestro-case/references/case-runtime.md', adaptCaseRuntime],
+  ['preview/skills/uipath-maestro-bpmn/references/bpmn-runtime.md', adaptBpmnRuntime],
 ]);
 
 function snapshotAdaptationFor(target) {
@@ -470,10 +470,10 @@ function verifySkillBody(skillsRoot, upstreamRoot, newCommit, target, source, ad
 
 function verifyExactMappings(skillsRoot, upstreamRoot, newCommit, mappings) {
   const adaptedTargets = new Map([
-    ['preview/uipath-maestro-flow/references/api.md', adaptFlowApi],
-    ['preview/uipath-maestro-case/examples/NotifyOnApproval.case.ts', adaptCaseExample],
-    ['preview/uipath-maestro-case/references/case-runtime.md', adaptCaseRuntime],
-    ['preview/uipath-maestro-bpmn/references/bpmn-runtime.md', adaptBpmnRuntime],
+    ['preview/skills/uipath-maestro-flow/references/api.md', adaptFlowApi],
+    ['preview/skills/uipath-maestro-case/examples/NotifyOnApproval.case.ts', adaptCaseExample],
+    ['preview/skills/uipath-maestro-case/references/case-runtime.md', adaptCaseRuntime],
+    ['preview/skills/uipath-maestro-bpmn/references/bpmn-runtime.md', adaptBpmnRuntime],
   ]);
   const skillTargets = new Set(skillMappings.map(({ target }) => target));
   for (const mapping of mappings) {
@@ -492,7 +492,7 @@ function verifyExactMappings(skillsRoot, upstreamRoot, newCommit, mappings) {
 
 function verifyFrontmatterAndPins(skillsRoot, newPin) {
   for (const skill of ['flow', 'case', 'bpmn']) {
-    const target = `preview/uipath-maestro-${skill}/SKILL.md`;
+    const target = `preview/skills/uipath-maestro-${skill}/SKILL.md`;
     const text = readText(path.join(skillsRoot, target));
     const frontmatter = text.match(/^---\n([\s\S]*?)\n---\n/);
     if (!frontmatter) fail(`${target} is missing YAML frontmatter`);
@@ -510,7 +510,7 @@ function verifyFrontmatterAndPins(skillsRoot, newPin) {
 
 function verifyDeadLinks(skillsRoot) {
   for (const skill of ['flow', 'case', 'bpmn']) {
-    const skillRoot = path.join(skillsRoot, `preview/uipath-maestro-${skill}`);
+    const skillRoot = path.join(skillsRoot, `preview/skills/uipath-maestro-${skill}`);
     const documents = [path.join(skillRoot, 'SKILL.md')];
     documents.push(
       ...walkFiles(path.join(skillRoot, 'references')).filter((file) => file.endsWith('.md')),
@@ -545,7 +545,7 @@ function routerRows(text) {
 }
 
 function verifyRouter(skillsRoot, upstreamRoot, newCommit) {
-  const target = readText(path.join(skillsRoot, 'preview/uipath-maestro-flow/SKILL.md'));
+  const target = readText(path.join(skillsRoot, 'preview/skills/uipath-maestro-flow/SKILL.md'));
   const source = gitShow(upstreamRoot, newCommit, `${sourceRoot}/skill/SKILL.md`).toString('utf8');
   const rows = routerRows(target);
   const sourceRows = routerRows(source);
@@ -555,19 +555,19 @@ function verifyRouter(skillsRoot, upstreamRoot, newCommit) {
   for (const row of rows) {
     const reference = row.match(/\]\(references\/([^)]+)\)/)?.[1];
     const example = row.match(/`examples\/([^`]+)`/)?.[1];
-    if (!reference || !fs.existsSync(path.join(skillsRoot, 'preview/uipath-maestro-flow/references', reference))) {
+    if (!reference || !fs.existsSync(path.join(skillsRoot, 'preview/skills/uipath-maestro-flow/references', reference))) {
       fail(`Flow router row has a missing reference: ${row}`);
     }
-    if (!example || !fs.existsSync(path.join(skillsRoot, 'preview/uipath-maestro-flow/examples', example))) {
+    if (!example || !fs.existsSync(path.join(skillsRoot, 'preview/skills/uipath-maestro-flow/examples', example))) {
       fail(`Flow router row has a missing example: ${row}`);
     }
   }
 }
 
 function verifyStalePaths(skillsRoot) {
-  const flow = readText(path.join(skillsRoot, 'preview/uipath-maestro-flow/SKILL.md'));
-  const caseSkill = readText(path.join(skillsRoot, 'preview/uipath-maestro-case/SKILL.md'));
-  const bpmn = readText(path.join(skillsRoot, 'preview/uipath-maestro-bpmn/SKILL.md'));
+  const flow = readText(path.join(skillsRoot, 'preview/skills/uipath-maestro-flow/SKILL.md'));
+  const caseSkill = readText(path.join(skillsRoot, 'preview/skills/uipath-maestro-case/SKILL.md'));
+  const bpmn = readText(path.join(skillsRoot, 'preview/skills/uipath-maestro-bpmn/SKILL.md'));
   if (/\bexample\//.test(flow) || /references\/(?:case|bpmn)-api\.md/.test(flow)) {
     fail('Flow SKILL.md contains an upstream-only path');
   }
@@ -577,7 +577,7 @@ function verifyStalePaths(skillsRoot) {
   if (/bpmn-api|\bexample\//.test(bpmn)) {
     fail('BPMN SKILL.md contains an upstream-only path');
   }
-  for (const file of walkFiles(path.join(skillsRoot, 'preview/uipath-maestro-case/examples'))) {
+  for (const file of walkFiles(path.join(skillsRoot, 'preview/skills/uipath-maestro-case/examples'))) {
     if (/case-bindings|\bexample\//.test(readText(file))) {
       fail(`${normalizeRelative(path.relative(skillsRoot, file))} contains an upstream-only path`);
     }
@@ -618,23 +618,23 @@ export function verifySnapshot({ skillsRoot, upstreamRoot, newCommit, newPin, ma
     skillsRoot,
     upstreamRoot,
     newCommit,
-    'preview/uipath-maestro-flow/SKILL.md',
+    'preview/skills/uipath-maestro-flow/SKILL.md',
     `${sourceRoot}/skill/SKILL.md`,
     adaptFlowSkill,
   );
   verifySkillBody(
     skillsRoot,
     upstreamRoot,
     newCommit,
-    'preview/uipath-maestro-case/SKILL.md',
+    'preview/skills/uipath-maestro-case/SKILL.md',
     `${sourceRoot}/skill/SKILL-case.md`,
     adaptCaseSkill,
   );
   verifySkillBody(
     skillsRoot,
     upstreamRoot,
     newCommit,
-    'preview/uipath-maestro-bpmn/SKILL.md',
+    'preview/skills/uipath-maestro-bpmn/SKILL.md',
     `${sourceRoot}/skill/SKILL-bpmn.md`,
     adaptBpmnSkill,
   );

skills/uipath-maestro-bpmn/SKILL.md

@@ -289,10 +289,14 @@ and honestly surfaced to the user as gaps when asked.
    and the process structure with the user (AskUserQuestion).
 5. **The diagram is mandatory.** Import is diagram-driven — every node needs a
    `BPMNShape`, every flow a `BPMNEdge`, or it will not appear on the canvas.
-6. **Node type is a child element, never an attribute.** Every `uipath:activity`
-   / `uipath:event` / `uipath:mapping` declares its type as
-   `<uipath:type value="<Type>" version="v1" />` inside the wrapper. Never write
-   `<uipath:activity type="…">` — the canvas will not recognize the node.
+6. **Preserve the registry's node-type shape.** Most `uipath:activity` /
+   `uipath:event` / `uipath:mapping` templates declare their type as a nested
+   `<uipath:type value="<Type>" version="v1" />`. Some runtime-authored
+   templates use the payload's `type` attribute instead; notably,
+   `Orchestrator.StartAgentJob` is a direct child of `bpmn:ServiceTask` with
+   `<uipath:activity type="Orchestrator.StartAgentJob" version="v1">`. Both
+   declarations are supported. Paste the selected registry template literally
+   and do not normalize one form into the other.
    Event extension types (`Intsvc.WaitForEvent`, `Intsvc.EventTrigger`,
    `Maestro.ReceiveMessageEvent`, `Maestro.SendMessageEvent`) must use
    `<uipath:event>`, including when the BPMN host is task-like such as