From eff7a27d757812d56ecb5caba96fcd9f79803170 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 14:33:16 +0300 Subject: [PATCH 01/10] docs: design spec for uipath-rpa execution maps (turn-count reduction) Co-Authored-By: Claude Fable 5 --- ...6-07-02-uipath-rpa-execution-map-design.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md diff --git a/docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md b/docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md new file mode 100644 index 0000000000..e03bd2065b --- /dev/null +++ b/docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md @@ -0,0 +1,138 @@ +# uipath-rpa Execution Map — Design + +**Date:** 2026-07-02 +**Status:** Draft — awaiting user review +**Scope:** `skills/uipath-rpa` only (first pilot; other skills follow later) + +## Problem + +Building anything with `uipath-rpa` costs 12–20+ assistant turns and many `uip` CLI calls. Cost drivers, with current-state anchors: + +1. **Discovery CLI round-trips** — per-activity triple (`activities find` → read `.md` → `get-default-xaml`) per Rule 21; `analyzer-rules list`; `packages versions/install`; each heavy call pays a ~22s Studio cold start (SKILL.md § Session Pre-warm). +2. **Reference reading** — several read-in-full mandates (`xaml-basics-and-rules.md`, `workflow-guide.md`, …) before authoring anything. +3. **One-activity-at-a-time authoring** — XAML Rule 18: "build one activity at a time, validate after each addition" → N activities ≈ N validate turns. +4. **Turn serialization** — SKILL.md § Call Batching covers only two batch points; no end-to-end turn plan. `uipath-maestro-flow` already solved this with rule #10 + a "Three-turn execution map" (`greenfield.md`); `uipath-rpa` has no equivalent. +5. **Precondition overhead** — project-discovery subagent round-trip even for greenfield builds where no project exists yet. + +## Goals & success criteria + +1. **Canonical greenfield XAML build (3–5 non-UIA activities): ≤5 assistant turns happy path** (including final report), ≤8 `uip` invocations, `validate` + `build` clean. One repair cycle adds ≤2 turns. +2. Brownfield edit (add/modify 1–3 activities): ≤4 turns. +3. Enforced by a coder-eval smoke task with a `max_turns` budget (see § Testing). +4. SKILL.md net size does not grow by more than ~10 lines — new content lives in `references/`. + +## Non-goals + +- UI Automation journeys. Capture is interactive and app-state-serialized by nature; UIA package details are forbidden in this skill per `skills/uipath-rpa/CLAUDE.md`. UIA keeps its read-in-full mandates (Rules 7/7a) untouched. +- Other skills (maestro-flow deepening, agents, api-workflow) — later phases. +- A repo-shipped machine-generated full activity catalog (rejected — see § Alternatives). +- Weakening the final quality gate: per-file `validate` clean + project `build` clean remain mandatory before "done". + +## Decisions log + +| Decision | Choice | Source | +|---|---|---| +| Primary target | File reads + CLI round trips + one-at-a-time loop + pattern memorization | user | +| Scope | `uipath-rpa` only first | user | +| Memorization mechanisms | Cross-session agent memory + in-context one-dense-map-file | user | +| Validate-loop relaxation | **Author-all, validate-once, bisect on failure** | **agent-substituted (user AFK) — confirm at review** | +| Turn budget numbers | ≤5 greenfield / ≤4 brownfield | agent-proposed — confirm at review | + +## Design + +Four components. All new prose follows `.claude/rules/token-optimization.md`. + +### 1. Execution maps — `references/execution-maps-guide.md` (new) + +One dense file the agent reads once per build ("in-context memorization"). Four journeys: + +- **Greenfield XAML** (no UIA) +- **Brownfield XAML edit** +- **Greenfield coded** +- **Brownfield coded edit** + +Each journey carries: + +- **Turn table** (T1/T2/T3/T4), maestro-flow style: exactly which tool calls go in ONE assistant message per turn. +- **Canonical T1 chain** — one `Bash`: pre-warm `&` + `uip rpa init` (with `--target-framework`/`--expression-language` per Rule 2a) `&&` `analyzer-rules list` `&&` `packages versions/install` for request-known packages; parallel `Read`s of the activity card, pattern card, and journey-relevant reference sections. +- **Scoped read list** — the minimal references REQUIRED for the happy path (the map + cards replace full reads of `workflow-guide.md`/`xaml-basics-and-rules.md` for card/pattern-covered work); explicit failure exits name which reference to open when leaving the happy path (validate errors → `validation-guide.md`; activity gotcha → `xaml/common-pitfalls.md`; off-card activity → Rule 21 triple). +- **Decision gates that must stay sequential** — `templates search` → `init` (Rule 2), any `AskUserQuestion`, UIA capture (out of scope → route to Rule 7 flow). +- **Tool-vocabulary note** cloned from maestro-flow SKILL.md so maps stay harness-portable. + +Happy-path turn shape (greenfield XAML): + +| Turn | Emits | +|---|---| +| T1 | Pre-warm + init/analyzer/packages chain (one `Bash`) ∥ card + pattern-card `Read`s | +| T2 | Author complete workflow — one `Write` of `Main.xaml` (or batched `Edit`s) ∥ `project.json` edits | +| T3 | One `Bash`: `validate --file-path` per file `&&` `build` | +| T4 | Completion report (SKILL.md § Completion Output) | + +`Read` of scaffolded files is unnecessary when authoring via full `Write` and init flags were explicit (expression language/target framework already known). + +### 2. Pattern card — `references/common-pattern-card.md` (new) + +Extends the proven `common-activity-card.md` mechanism from single activities to **multi-activity patterns**. Structure mirrors the activity card: package anchor + verified version per entry, property-complete snippet, variables block, notes, long-form pointer. + +- **Candidate patterns (~12 initial):** Excel read-range→for-each-row→write-range; CSV read/write; text file read/write/append; file ops (exists/copy/move/delete); HTTP request + JSON deserialize; send mail (SMTP, with Outlook/O365 variant notes); DataTable build/filter/add-row; queue produce (AddQueueItem) and consume loop (GetTransactionItem + SetTransactionStatus); RetryScope wrap; InvokeWorkflowFile with arguments. Final list picked at implementation by frequency in `tests/tasks/uipath-rpa/` + known top user asks. +- **Supersession rule:** for a card-listed pattern, skip the Rule 21 discovery triple for every activity inside the pattern snippet. Precedence: **activity/pattern card → agent memory → Rule 21 triple**. +- **Staleness guard:** every entry stamps package id + verified version. `validate`/`build` is the runtime guard — on rejection of a card snippet, fall back to the Rule 21 triple for that activity and report the stale entry (`/uipath-feedback` + repo issue). +- **Maintenance:** `.maintenance/pattern-card-maintenance.md` documents regeneration: scratch project, author each pattern, `validate` + `build` clean, update version stamps. Manual, human-reviewed — no build system (repo rule). +- UIA activities stay off-card (CLAUDE.md boundary). + +### 3. Batch authoring + single validation gate (Rule 18 rewrite) + +Replace XAML Rule 18 "Start minimal, iterate to correct — one activity at a time, validate after each addition" with: + +> **[XAML] Batch-author, single gate.** Author the complete workflow in one pass. Then per-file `validate` to clean, then one project `build` (Rule 3 cadence otherwise unchanged, 5-attempt caps stay). On validate/build failure: fix by error category (Rule 19); if the offending activity is ambiguous across >2 errors, bisect — re-validate with half the new activities stubbed out. Card/pattern/memory-sourced activities carry low hallucination risk; this is what makes batch authoring safe. + +Companion edits: SKILL.md § Call Batching "per-file validate / per-activity authoring loop" do-not-batch bullet is superseded; § Call Batching itself collapses to a pointer at the execution maps (keeping the sequential-by-design gates list). + +### 4. Cross-session memory protocol (section inside execution-maps-guide.md) + +Harness-conditional — engages only when the harness provides persistent memory; silently skipped otherwise (graceful degradation, per repo self-containment rules). + +- **Save, after project `build` is clean:** (a) validated XAML snippet per off-card activity, keyed by activity class + package major.minor + date; (b) error→root-cause→fix triples that cost >1 validate attempt; (c) cross-version gotchas. +- **Recall, at authoring-phase start:** match by activity class + package major. Hit ⇒ skip `find`/`get-default-xaml`/doc read for that activity. `validate` + `build` still gate everything — memory never bypasses validation. +- **Never memorize:** project-specific facts (paths, asset names, connections — those belong in `project-context.md`), anything UIA (selectors/targets are per-app; CLAUDE.md boundary), secrets. +- **Expiry:** on validation failure of a recalled snippet, delete/overwrite that memory entry. + +### SKILL.md integration (target net delta ≈ 0; hard cap +10 lines per Goals #4) + +1. § Call Batching → replaced by short § Execution Maps routing to the new guide (shorter than current text). +2. Rule 18 rewritten (component 3). +3. Rule 21 amended: pattern card added as an allowlist source; card → memory → triple precedence. +4. § Precondition: greenfield (no `project.json` found) skips the discovery subagent; agent writes `project-context.md` itself at completion from what it just created. +5. § Completion Output: add conditional "save memory entries" step. +6. Task Navigation: one new row for the execution maps guide. + +## Error handling & risks + +| Risk | Mitigation | +|---|---| +| Stale card/pattern snippet vs installed package | Version stamp per entry; `validate`/`build` runtime guard; fallback to Rule 21 triple; staleness report path | +| Batch-author failure harder to localize | Error-category fix flow (Rule 19) + bounded bisect; 5-attempt caps unchanged | +| Stale memory across package versions | Keys include package major.minor; validation gate; delete-on-failure expiry | +| Map contradicts existing rules | Implementation pass audits every SKILL.md rule cross-reference; maps cite rules, never restate them | +| Harness without memory/parallel-tool support | Memory protocol conditional; maps state per-turn intent so serial harnesses still minimize CLI calls | +| SKILL.md bloat | Hard budget: net ≤ +10 lines | + +## Testing + +Per `.claude/rules/test-writing.md` workflow (`/test-coverage` → `/generate-task` → `/lint-task` → run): + +1. **New smoke task** `tests/tasks/uipath-rpa/...`: canonical greenfield XAML build with a `max_turns` override enforcing the turn budget; criteria: workflow file exists with expected activities (`file_contains`), `validate` and `build` executed clean (`command_executed`), `--output json` usage check. +2. **Baseline:** run the same prompt against the pre-change skill once to record current turn count in the PR (before/after claim). +3. Existing uipath-rpa tasks re-run to catch regressions from the Rule 18/21 changes. + +## Alternatives considered + +- **B — Batching-only port of maestro-flow rule #10.** Rejected as insufficient: leaves discovery triples, read-in-full cost, and the per-activity validate loop untouched (user asked for all four cost classes). +- **C — Repo-shipped machine-generated activity catalog JSON (full property surfaces).** Rejected: drifts against per-project installed package versions; heavy regeneration burden; contradicts the co-versioned-docs philosophy in `skills/uipath-rpa/CLAUDE.md`. The human-verified pattern card + validation guard captures most of the value at a fraction of the risk. + +## Open questions for review + +1. Validate-loop choice: confirm **author-all/validate-once** over the tiered variant (card-known batch freely, unknown activities keep incremental loop). Agent-substituted while you were AFK. +2. Turn budgets (≤5 greenfield / ≤4 brownfield) — right bar? +3. Initial pattern list (~12 candidates above) — additions/removals? +4. OK to skip the project-discovery subagent for greenfield builds? From 907adc873299286d580d65d687b9946b7c4735ad Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 14:39:25 +0300 Subject: [PATCH 02/10] docs: implementation plan for uipath-rpa execution maps Co-Authored-By: Claude Fable 5 --- .../2026-07-02-uipath-rpa-execution-maps.md | 498 ++++++++++++++++++ 1 file changed, 498 insertions(+) create mode 100644 docs/superpowers/plans/2026-07-02-uipath-rpa-execution-maps.md diff --git a/docs/superpowers/plans/2026-07-02-uipath-rpa-execution-maps.md b/docs/superpowers/plans/2026-07-02-uipath-rpa-execution-maps.md new file mode 100644 index 0000000000..1b4c539845 --- /dev/null +++ b/docs/superpowers/plans/2026-07-02-uipath-rpa-execution-maps.md @@ -0,0 +1,498 @@ +# uipath-rpa Execution Maps Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Cut a canonical uipath-rpa greenfield build from 12–20+ assistant turns to ≤5 (brownfield ≤4) via journey execution maps, a pre-validated pattern card, batch authoring with a single validation gate, and a cross-session memory protocol. + +**Architecture:** Four additions to `skills/uipath-rpa/`: (1) `references/execution-maps-guide.md` — one dense per-journey turn plan incl. the memory protocol; (2) `references/common-pattern-card.md` — multi-activity pre-validated XAML snippets extending the proven `common-activity-card.md` mechanism; (3) SKILL.md surgical edits (Rule 18 rewrite, Call Batching → Execution Maps, Rule 21 precedence, greenfield precondition skip, completion memory step); (4) a coder-eval smoke task enforcing the turn budget. Spec: `docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md`. + +**Tech Stack:** Markdown skill docs, `uip` CLI (local 1.0.0-alpha, verified present), coder-eval task YAML, repo validation scripts (`hooks/validate-skill-descriptions.sh`, `scripts/check-skill-status.py`, `scripts/check-cli-verbs.py`), repo slash commands (`/test-coverage`, `/generate-task`, `/lint-task`). + +**Execution autonomy: autonomous** + +**Stop conditions:** +- `uip rpa init`/`validate`/`build` unusable locally (CLI errors unrelated to authored content) → pattern-card entries cannot be verified; stop card tasks, finish remaining tasks, report. +- A SKILL.md `old_string` no longer matches (upstream drift) → stop that edit, re-read SKILL.md, adapt, continue. + +## Global Constraints + +- All new prose follows `.claude/rules/token-optimization.md` (terse mode) and `.claude/rules/content-quality.md`. +- SKILL.md hard cap: net ≤ +10 lines (spec Goals #4). Measure with `git diff --stat` at Task 2 end. +- No UIA subcommands/flags/artifact names anywhere (per `skills/uipath-rpa/CLAUDE.md`). UIA activities stay off all cards. +- Skill stays self-contained: no reads of other skills' files; links relative to file location and must resolve. +- Every card snippet MUST be validated by `uip rpa validate` + `uip rpa build` in the scratch project before it enters the card. Unverified entries are dropped, never stamped. +- CLI examples use `--output json` when output is parsed; placeholders ``. +- Scratch project lives in the session scratchpad dir, never committed. +- Commit after each task; branch `feat/uipath-rpa-execution-maps` (already created, spec committed). + +--- + +### Task 1: Create `references/execution-maps-guide.md` + +**Files:** +- Create: `skills/uipath-rpa/references/execution-maps-guide.md` +- Read first (sourcing): `skills/uipath-rpa/references/cli-reference.md` (init/validate/build/packages/analyzer-rules sections), `skills/uipath-rpa/references/environment-setup.md` (§ Template selection) + +**Interfaces:** +- Produces: file path `references/execution-maps-guide.md` with anchors `#cross-session-memory` and `#failure-exits` — Tasks 2 and 6 link to them. + +- [ ] **Step 1: Source exact CLI syntax.** Read `references/cli-reference.md` and `references/environment-setup.md`. Transcribe exact flags for: `uip rpa init`, `analyzer-rules list`, `packages versions`, `packages install`, `validate`, `build`. Where the draft below disagrees with cli-reference.md, cli-reference.md wins. + +- [ ] **Step 2: Write the file.** Content (adjust command syntax per Step 1; keep structure and rule citations): + +````markdown +# Execution Maps — Turn-Budgeted Build Journeys + +One dense file, read once per build. Fixes which tool calls go in which assistant turn. Budgets (happy path, incl. final report): **greenfield ≤5 turns, brownfield ≤4**. One repair cycle adds ≤2. + +> **Tool vocabulary.** Tool names use Claude Code conventions: `Edit` = in-place string replacement, `Write` = full-file write, `Read`/`Glob`/`Grep` = file read/search, `Bash` = shell. On another harness, map each to its equivalent. Harness cannot emit parallel tool calls → keep the same per-turn grouping as consecutive calls; the CLI chains still collapse round-trips. + +## Source precedence — every activity you author + +1. **Card** — [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md) +2. **Agent memory** — validated snippet from a prior session (see [§ Cross-session memory](#cross-session-memory)) +3. **Rule 21 triple** — `activities find` → `.md` read → `get-default-xaml`, fanned out in T1 + +`validate` + `build` gate all three. Card/memory hits skip discovery, never the gate. + +## Sequential gates — never batch across these + +- `templates search` → `init` (Rule 2): search result (possibly an `AskUserQuestion`) picks `--template-package-id`. +- Rule 2a framework/language question when the request carries no signal. +- Any `AskUserQuestion` or consent gate. +- UIA capture (Rule 7) — out of map scope entirely; UIA journeys keep their own flow. + +## Journey: Greenfield XAML (no UIA) + +Skip the project-discovery subagent — no project exists (SKILL.md § Precondition). Write `project-context.md` + `AGENTS.md` yourself at T4. + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Scaffold + context** | ONE `Bash` chain: `uip rpa init` (explicit `--target-framework`, `--expression-language`, Rule 2a) `&&` `analyzer-rules list --project-dir` `&&` one `packages versions --include-prerelease` per request-known package ∥ parallel `Read`: [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md), [xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md) (Rule 22) ∥ memory recall (if harness has memory) ∥ Rule 21 `find` fan-out for any off-card activity | +| **T2 — Author + install** | One `Write` per workflow file — complete, all activities (Rule 18) ∥ `Edit` `project.json` (`fileInfoCollection` for test cases, Rule 10) ∥ ONE `Bash`: `packages install` per package, version from T1 `versions` output ∥ Rule 21 doc `Read`s + `get-default-xaml` for off-card activities | +| **T3 — Gate** | ONE `Bash`: `validate --file-path "" --project-dir "" --output json` per file `&&` `build "" --output json` | +| **T4 — Report** | § Completion Output + write `project-context.md`/`AGENTS.md` + memory save ([§ Cross-session memory](#cross-session-memory)) | + +No `Read` of scaffolded files in T2: init flags were explicit, so `expressionLanguage`/`targetFramework` are known; full-file `Write` replaces scaffolded `Main.xaml`. + +**Repair cycle (validate/build failure):** one turn — `Edit` fixes by error category (Rule 19); next turn — re-run the T3 chain. >2 errors with ambiguous origin → bisect: stub out half the new activities, re-validate. Caps: 5 attempts per loop (Rule 3). + +## Journey: Brownfield XAML edit + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Context** | § Precondition context check ∥ `Read` `project.json` + target `.xaml` + cards ∥ ONE `Bash`: `analyzer-rules list` ∥ memory recall ∥ off-card `find` fan-out | +| **T2 — Edit** | Batched `Edit`s (anchor each on its own target block — same-file Edits serialize; overlapping anchors fail) ∥ `packages install` `Bash` if new dependencies | +| **T3 — Gate** | ONE `Bash`: per-file `validate` `&&` `build` | +| **T4 — Report** | § Completion Output + memory save | + +## Journey: Greenfield coded + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Scaffold + context** | ONE `Bash` chain: `init` `&&` `analyzer-rules list` `&&` `packages versions` per known package ∥ `Read` [assets/codedworkflow-template.md](../assets/codedworkflow-template.md) + [coded/coding-guidelines.md](coded/coding-guidelines.md) + `.local/docs/.../coded/coded-api.md` for known packages ∥ memory recall | +| **T2 — Author + install** | `Write` each `.cs` (Rules 13–19) ∥ `Edit` `project.json` (`entryPoints` Rule 15, `fileInfoCollection` Rule 10) ∥ `packages install` `Bash` | +| **T3 — Gate** | ONE `Bash`: per-file `validate` `&&` `build` | +| **T4 — Report** | § Completion Output + memory save | + +## Journey: Brownfield coded edit + +Same as brownfield XAML with coded reads: T1 `Read` target `.cs` + `coded-api.md` for touched services; T2 `Edit`s ∥ install; T3 gate; T4 report. + +## Failure exits + +| Symptom | Open | +|---|---| +| `validate` structural/reference errors | [validation-guide.md](validation-guide.md) | +| XAML activity gotcha (property conflicts, scope) | [xaml/common-pitfalls.md](xaml/common-pitfalls.md) | +| Coded `CS*` errors | [coded/coding-guidelines.md § Common Issues](coded/coding-guidelines.md) | +| Card snippet rejected by validate/build | Fall back to Rule 21 triple for that activity; report stale entry via `/uipath-feedback` | +| Anything UIA | Rule 7 flow — leave this map | + +## Cross-session memory + +Harness-conditional: engage only when the harness provides persistent memory; otherwise skip silently. + +**Recall — T1 of every journey.** Match saved entries by activity class + package `major.minor`. Hit ⇒ that activity skips the Rule 21 triple. `validate`/`build` still gate. + +**Save — after project `build` is clean (T4).** Save only: +1. Validated XAML snippet per off-card activity — key: activity class + package `major.minor` + date. +2. Error→root-cause→fix triples that cost >1 validate attempt. +3. Cross-version package gotchas. + +**Never save:** project-specific facts (paths, asset names, connections — belong in `project-context.md`), anything UIA (selectors/targets are per-app), secrets. + +**Expiry:** recalled snippet fails validation → delete/overwrite that entry, fall back to Rule 21 triple. +```` + +- [ ] **Step 3: Verify links resolve.** + +Run: `cd skills/uipath-rpa/references && for f in common-activity-card.md common-pattern-card.md xaml/xaml-basics-and-rules.md validation-guide.md xaml/common-pitfalls.md coded/coding-guidelines.md ../assets/codedworkflow-template.md; do [ -f "$f" ] || echo "MISSING $f"; done` +Expected: only `MISSING common-pattern-card.md` (created in Task 3 — acceptable forward link within this branch; re-run after Task 3 with zero output). + +- [ ] **Step 4: Verify no retired verbs / no UIA leakage.** + +Run: `python3 scripts/check-cli-verbs.py 2>/dev/null || true` and `grep -nE 'interact click|interact type|snapshot capture|Target_Definition|indicate-element|TARGET-[0-9]' skills/uipath-rpa/references/execution-maps-guide.md` +Expected: no matches from the grep; check-cli-verbs reports no new findings. + +- [ ] **Step 5: Commit.** + +```bash +git add skills/uipath-rpa/references/execution-maps-guide.md +git commit -m "feat(uipath-rpa): add execution maps guide — turn-budgeted build journeys" +``` + +--- + +### Task 2: SKILL.md integration edits + +**Files:** +- Modify: `skills/uipath-rpa/SKILL.md` (7 surgical edits, A–G) + +**Interfaces:** +- Consumes: `references/execution-maps-guide.md` (Task 1), anchor `#cross-session-memory`. +- Produces: Rule 18 new text and § Execution Maps section that Task 6's eval prompt relies on behaviorally. + +- [ ] **Step 1: Edit A — Rule 18 rewrite.** + +old_string: +``` +18. **[XAML] Start minimal, iterate to correct** — build one activity at a time, validate after each addition. +``` +new_string: +``` +18. **[XAML] Batch-author, single gate** — author the complete workflow in one pass, sourcing each activity card → memory → Rule 21 triple (precedence in [execution-maps-guide.md](references/execution-maps-guide.md)). Then per-file `validate` to clean, then one project `build` (Rule 3 cadence, 5-attempt caps unchanged). On failure: fix by error category (Rule 19); >2 errors with ambiguous origin → bisect (stub out half the new activities, re-validate). +``` + +- [ ] **Step 2: Edit B — replace § Call Batching with § Execution Maps.** Replace the entire section from the `### Call Batching (Both Modes)` heading up to (not including) `### Coded-Specific Rules` with: + +``` +### Execution Maps (Both Modes) + +**Follow the journey map in [execution-maps-guide.md](references/execution-maps-guide.md) for every build or edit** — it fixes which tool calls batch into which assistant turn (greenfield ≤5 turns, brownfield ≤4). Within a turn: chain dependent `uip` calls with `&&` in one `Bash`; emit independent `Bash`/`Read`/`Edit` calls as parallel tool uses. Split turns only where a call needs an earlier call's stdout or a file mutation. Rule 21 discovery for off-card activities fans out inside T1/T2 — all K `find`s parallel, then all K doc `Read`s, then all K `get-default-xaml`s — never one activity at a time. + +**Sequential by design — never batch across:** `templates search` → `init` (Rule 2 decision gate); any `AskUserQuestion` or consent gate; UIA capture flows (Rule 7). +``` + +- [ ] **Step 3: Edit C — Rule 21 card bullet gains pattern card + memory precedence.** + +old_string: +``` + - **Card-listed activities:** check [references/common-activity-card.md](references/common-activity-card.md) first; if the activity is on the card, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read. +``` +new_string: +``` + - **Card-listed activities and patterns:** check [references/common-activity-card.md](references/common-activity-card.md) and [references/common-pattern-card.md](references/common-pattern-card.md) first; on a card hit, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read. Precedence: card → agent memory ([execution-maps-guide.md § Cross-session memory](references/execution-maps-guide.md#cross-session-memory)) → full triple. A memory hit substitutes for the triple only; `validate`/`build` still gate. +``` + +- [ ] **Step 4: Edit D — greenfield skips discovery agent.** + +old_string: +``` +**If the file does NOT exist** → run the discovery flow below. +``` +new_string: +``` +**If the file does NOT exist** → if a `project.json` exists, run the discovery flow below. **Greenfield (no `project.json`): skip the discovery agent** — nothing to discover. After the build completes, write both context files yourself (step 3 below) from what you just created: structure, dependencies, entry points. +``` + +- [ ] **Step 5: Edit E — Rule 4 cadence alignment.** + +old_string: +``` +4. **ALWAYS validate files as you go AND verify the project builds before declaring done.** After every create or edit: per-file `validate` to clean. +``` +new_string: +``` +4. **ALWAYS bring every touched file to per-file `validate` clean AND verify the project builds before declaring done.** Cadence per Rule 18: batch-author, then validate. +``` +(If the exact sentence differs, adapt: keep the "validate clean + build mandatory" meaning, drop "after every create or edit".) + +- [ ] **Step 6: Edit F — Completion Output memory step.** After the numbered pre-report list (item 4, "If the plan is fully checked off…"), insert: + +``` +Then, if the harness provides persistent memory, save validated patterns per [execution-maps-guide.md § Cross-session memory](references/execution-maps-guide.md#cross-session-memory) before reporting. +``` + +- [ ] **Step 7: Edit G — Task Navigation row.** Insert as the second row of the Task Navigation table (after the header separator and the Legacy row): + +``` +| **Plan the build's turn structure** | Both | [execution-maps-guide.md](references/execution-maps-guide.md) — read first for any build/edit journey | +``` + +- [ ] **Step 8: Verify size budget + frontmatter + links.** + +Run: `git diff --stat skills/uipath-rpa/SKILL.md && bash hooks/validate-skill-descriptions.sh && python3 scripts/check-skill-status.py` +Expected: net line delta ≤ +10; description hook passes (frontmatter untouched); status check passes (no status change). + +- [ ] **Step 9: Commit.** + +```bash +git add skills/uipath-rpa/SKILL.md +git commit -m "feat(uipath-rpa): route builds through execution maps; batch-author with single validate gate" +``` + +--- + +### Task 3: Pattern card batch 1 — System-package patterns + validation harness + +**Files:** +- Create: `skills/uipath-rpa/references/common-pattern-card.md` +- Scratch (not committed): `/patterncard/` UiPath project + +**Interfaces:** +- Consumes: entry format precedent from `references/common-activity-card.md` (package anchor, snippet, notes, long-form pointer). +- Produces: card file with H3 entry per pattern; Task 4 appends to it; Task 2's Edit C links to it. + +- [ ] **Step 1: Locate source docs.** For each batch-1 pattern, confirm the doc file exists and note the exact activity class: + +Run: `ls skills/uipath-rpa/references/activity-docs/UiPath.System.Activities/26.4/activities/ | grep -iE 'text|file|csv|datatable|adddatarow|filter|build|queue|transaction|retry|invokeworkflow'` + +Batch-1 patterns (all `UiPath.System.Activities` 26.4 unless the grep shows CSV lives elsewhere — follow the grep): +1. **Text file read → transform → write/append** (`ReadTextFile`, `WriteTextFile`, append variant) +2. **File ops** (path-exists check, copy/move/delete, create directory) +3. **CSV read/write** +4. **DataTable build → add rows → filter** +5. **Queue produce** (`AddQueueItem`) and **queue consume loop** (`GetTransactionItem` + `SetTransactionStatus` — cite the reframework-guide queue-guard note) +6. **Retry wrap** (`RetryScope` around a fragile action) +7. **Invoke Workflow File with in/out arguments** + +Read each pattern's activity `.md` docs in one parallel batch. + +- [ ] **Step 2: Scaffold scratch validation project.** + +Run (scratchpad dir from session): `cd && mkdir -p patterncard && cd patterncard && uip rpa init . --project-name PatternCard --target-framework Windows --expression-language VisualBasic --output json` (exact init syntax per cli-reference.md — adapt if init takes a directory arg differently). +Expected: `project.json` scaffolded; note installed `UiPath.System.Activities` version. + +- [ ] **Step 3: Author one probe workflow per pattern.** For each pattern, write `/patterncard/Pattern_.xaml` containing the candidate snippet inside a complete `` root (root boilerplate from `common-activity-card.md` § How to read the snippets). Property-complete per the activity docs: include every required property and use-case-relevant optionals — starter-XAML omission of defaults is exactly the trap the card exists to avoid. + +- [ ] **Step 4: Validate every probe.** + +Run: `cd /patterncard && for f in Pattern_*.xaml; do uip rpa validate --file-path "$f" --project-dir . --output json; done && uip rpa build . --output json` +Expected: 0 errors per file, build clean. Fix by error category; 5-attempt cap per file. A pattern that cannot reach clean is dropped from the card (record why in the commit message). + +- [ ] **Step 5: Write the card file.** Header mirrors `common-activity-card.md`; per-entry schema: + +````markdown +# Common Pattern Card + +**Package anchor:** `UiPath.System.Activities` — every entry below CLI-verified (`validate` + `build` clean) on the stamped version. + +Copy-safe multi-activity snippets. **Supersedes the Rule 21 discovery procedure for every activity inside a listed pattern.** For activities outside these patterns, Rule 21 applies. Precedence: card → agent memory → Rule 21 triple ([execution-maps-guide.md](execution-maps-guide.md)). If `validate`/`build` rejects a card snippet: fall back to the Rule 21 triple for that activity and report the stale entry via `/uipath-feedback`. + +Snippets are fragments for a complete `` root — boilerplate rules identical to [common-activity-card.md § How to read the snippets](common-activity-card.md). VB expression form; C# projects: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md). + +## Card entries + + + +--- + +### +**Activities:** `` · `` … +**Packages:** `` +**Variables:** + +**Snippet:** +```xml + +``` + +**Notes:** +**Long-form:** [`activity-docs///activities/.md`](activity-docs///activities/.md) +```` + +Fill one entry per validated pattern with the exact XAML that passed Step 4. + +- [ ] **Step 6: Re-run Task 1 Step 3 link check.** +Expected: zero output (pattern card now exists). + +- [ ] **Step 7: Commit.** + +```bash +git add skills/uipath-rpa/references/common-pattern-card.md +git commit -m "feat(uipath-rpa): pattern card batch 1 — System package patterns, CLI-verified" +``` + +--- + +### Task 4: Pattern card batch 2 — Excel, Mail, HTTP + +**Files:** +- Modify: `skills/uipath-rpa/references/common-pattern-card.md` (append entries) +- Scratch: same `/patterncard/` project + +**Interfaces:** +- Consumes: card schema from Task 3; scratch project. +- Produces: final card entry list for the "Card entries" index line. + +- [ ] **Step 1: Install packages + read docs.** + +Run: `cd /patterncard && uip rpa packages versions --package-id UiPath.Excel.Activities --include-prerelease --project-dir . --output json` (same for `UiPath.Mail.Activities`, `UiPath.WebAPI.Activities` — if `packages versions` shows WebAPI under a different id, use the id from `activities find --query http`). Then one `packages install` per package at the latest version. +Read bundled docs in parallel: `activity-docs/UiPath.Excel.Activities/3.6/…`, `activity-docs/UiPath.Mail.Activities/2.8/…`, `activity-docs/UiPath.Web.Activities/2.5/…`; prefer `.local/docs/packages//` in the scratch project once installed (more accurate). + +Batch-2 patterns: +1. **Excel: process scope → read range → for-each row → write range** +2. **Mail: send SMTP message** (notes line points at Outlook/O365 variants' doc paths, no separate snippet) +3. **HTTP request → deserialize JSON** + +- [ ] **Step 2: Author probes, validate, append entries.** Same procedure as Task 3 Steps 3–5. Multi-package entries stamp each package version. Update the "Card entries" index line and the header package-anchor line to list all verified package+version pairs. + +- [ ] **Step 3: Full-card re-verification.** + +Run: `cd /patterncard && for f in Pattern_*.xaml; do uip rpa validate --file-path "$f" --project-dir . --output json; done && uip rpa build . --output json` +Expected: still clean with all packages installed (catches cross-package conflicts). + +- [ ] **Step 4: Commit.** + +```bash +git add skills/uipath-rpa/references/common-pattern-card.md +git commit -m "feat(uipath-rpa): pattern card batch 2 — Excel, Mail, HTTP patterns, CLI-verified" +``` + +--- + +### Task 5: `.maintenance/pattern-card-maintenance.md` + +**Files:** +- Create: `skills/uipath-rpa/.maintenance/pattern-card-maintenance.md` + +- [ ] **Step 1: Write the file.** Full content: + +````markdown +# Pattern Card Maintenance + +Regeneration procedure for [references/common-pattern-card.md](../references/common-pattern-card.md). Run when: a stamped package ships a new minor/major, a staleness report arrives (`/uipath-feedback` or repo issue), or a new pattern is added. + +## Procedure + +1. Scratch project (never committed): `uip rpa init` a blank Windows/VisualBasic project in a temp dir. +2. `uip rpa packages install` every package stamped on the card, at the target (new) versions — `--include-prerelease`. +3. One probe workflow per card entry: paste the entry's snippet inside a complete `` root (boilerplate per [common-activity-card.md § How to read the snippets](../references/common-activity-card.md)). +4. Gate: per-file `uip rpa validate --file-path "" --project-dir "" --output json` to 0 errors, then `uip rpa build "" --output json` clean. +5. Failing entry → fix from `{PROJECT_DIR}/.local/docs/packages//activities/.md` (post-install, authoritative for the new version), re-gate. Unfixable → remove the entry from the card. +6. Update every entry's version stamp + the header package-anchor line. Entries never carry a version they were not gated against. +7. New pattern candidates qualify by frequency: appears in ≥2 `tests/tasks/uipath-rpa/` tasks or is a documented top user ask. Keep the card ≤ ~15 entries — it is a hot-path read, not a catalog. + +## Rules + +- CLI-gate before stamp — no exceptions, no "obviously fine" edits. +- UIA activities never enter this card (`skills/uipath-rpa/CLAUDE.md` boundary). +- Prose follows `.claude/rules/token-optimization.md`. +```` + +- [ ] **Step 2: Commit.** + +```bash +git add skills/uipath-rpa/.maintenance/pattern-card-maintenance.md +git commit -m "docs(uipath-rpa): pattern card maintenance procedure" +``` + +--- + +### Task 6: Turn-budget eval task + +**Files:** +- Create: `tests/tasks/uipath-rpa/execution-map/execution-map_greenfield.yaml` (one task per leaf dir) + +**Interfaces:** +- Consumes: behavioral contract from Task 2 (maps followed, validate+build gate) and Task 3 (text-file pattern on card). + +- [ ] **Step 1: Coverage + scaffold via repo workflow.** Run `/test-coverage uipath-rpa`, then `/generate-task greenfield XAML build inside the execution-map turn budget (≤8 turns), text-file automation, validate+build clean`. Reconcile the scaffold with the target YAML below (target wins on intent; scaffold wins on schema syntax — exact `agent:` override key, criterion field names — verify against `tests/README.md` and an existing task such as `tests/tasks/uipath-rpa/xaml_test_case.yaml`). + +- [ ] **Step 2: Target YAML.** + +```yaml +task_id: skill-rpa-execution-map-greenfield +description: > + Greenfield XAML build must finish inside the execution-map turn budget: + scaffold, batch-author, and gate (validate + build) a small text-file + workflow in at most 8 turns, proving the execution map + pattern card + eliminate per-activity discovery and validation round-trips. +tags: [uipath-rpa, smoke, mode:build] + +agent: + max_turns: 8 + +initial_prompt: | + Create a UiPath XAML automation project named TextReport. The workflow must + read ./input/orders.txt, log its contents, and append a processed marker + line to the file. The task is not complete until `uip rpa validate` passes + for the workflow file and `uip rpa build` passes for the project. + Do NOT ask for approval, confirmation, or feedback. + Before starting, load the uipath-rpa skill and follow its workflow. + +success_criteria: + - type: file_exists + description: "Workflow file created" + path: "TextReport/Main.xaml" + weight: 1.5 + pass_threshold: 1.0 + + - type: command_executed + description: "Per-file validate ran" + tool_name: "Bash" + command_pattern: '(uip|\$UIP)\s+rpa\s+validate\s+.*--file-path' + min_count: 1 + weight: 3.0 + pass_threshold: 1.0 + + - type: command_executed + description: "Project build gate ran" + tool_name: "Bash" + command_pattern: '(uip|\$UIP)\s+rpa\s+build\b' + min_count: 1 + weight: 3.0 + pass_threshold: 1.0 + + - type: command_not_executed + description: "No per-activity discovery for card-covered activities (pattern card supersedes get-default-xaml)" + tool_name: "Bash" + command_pattern: '(uip|\$UIP)\s+rpa\s+activities\s+get-default-xaml' + weight: 1.0 + pass_threshold: 1.0 + + - type: command_executed + description: "JSON output discipline" + tool_name: "Bash" + command_pattern: '(uip|\$UIP)\s+rpa\s+.*--output\s+json' + min_count: 1 + weight: 1.0 + pass_threshold: 1.0 +``` + +Schema adjustments from Step 1 apply (e.g., if `max_turns` lives at task top level rather than under `agent:`, or `command_not_executed` uses a different shape). If the sandbox needs `input/orders.txt` seeded, copy the seeding mechanism from an existing task/shared scripts; if none exists, change the prompt to have the workflow create the file first, and drop the path assumption. `file_exists` path must match where the map scaffolds the project — adjust after observing the scaffold layout (init may create `TextReport/` at CWD root). + +- [ ] **Step 3: Lint.** Run `/lint-task tests/tasks/uipath-rpa/execution-map/execution-map_greenfield.yaml`. Fix all High findings; run `/audit-verbs` only if lint raises CLI-verb reachability. + +- [ ] **Step 4: Run the task if the local coder-eval harness is available; otherwise record honestly.** Attempt per `tests/README.md` (make target or runner script). If runnable, also run the same prompt once against the pre-change skill (`git stash` / main checkout of `skills/uipath-rpa/`) and record before/after turn counts for the PR (spec Testing #2). If the harness/env (sandbox, login) is unavailable locally, note "passing-run claim pending CI" in the eventual PR body — do not fabricate a claim. + +- [ ] **Step 5: Commit.** + +```bash +git add tests/tasks/uipath-rpa/execution-map/execution-map_greenfield.yaml +git commit -m "test(uipath-rpa): smoke task enforcing execution-map turn budget" +``` + +--- + +### Task 7: Final sweep + spec coverage check + +**Files:** +- Modify (only if sweep finds issues): files from Tasks 1–6 + +- [ ] **Step 1: Repo validation sweep.** + +Run: `bash hooks/validate-skill-descriptions.sh && python3 scripts/check-skill-status.py && python3 scripts/check-cli-verbs.py` +Expected: all pass; no README regeneration needed (no status change). + +- [ ] **Step 2: Cross-file consistency.** Grep the new/edited files for: rule-number citations that don't exist in SKILL.md (`grep -oE 'Rule [0-9]+[a-z]?' skills/uipath-rpa/references/execution-maps-guide.md | sort -u` — verify each against SKILL.md), broken relative links (re-run Task 1 Step 3 list plus card links), UIA-forbidden terms (Task 1 Step 4 grep across all new files). + +- [ ] **Step 3: Spec coverage check.** Re-read `docs/superpowers/specs/2026-07-02-uipath-rpa-execution-map-design.md` § Design 1–4 and § SKILL.md integration 1–6; point each requirement at a commit. Gaps → fix now. + +- [ ] **Step 4: Commit any fixes.** + +```bash +git add -A && git commit -m "chore(uipath-rpa): execution-maps final sweep fixes" +``` +(Skip commit if the sweep was clean.) From d7095d6634e0d9e5436df4c354de8d0366319888 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 14:42:06 +0300 Subject: [PATCH 03/10] =?UTF-8?q?feat(uipath-rpa):=20add=20execution=20map?= =?UTF-8?q?s=20guide=20=E2=80=94=20turn-budgeted=20build=20journeys?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .../references/execution-maps-guide.md | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 skills/uipath-rpa/references/execution-maps-guide.md diff --git a/skills/uipath-rpa/references/execution-maps-guide.md b/skills/uipath-rpa/references/execution-maps-guide.md new file mode 100644 index 0000000000..5fdf0ab467 --- /dev/null +++ b/skills/uipath-rpa/references/execution-maps-guide.md @@ -0,0 +1,88 @@ +# Execution Maps — Turn-Budgeted Build Journeys + +One dense file, read once per build. Fixes which tool calls go in which assistant turn. Budgets (happy path, incl. final report): **greenfield ≤5 turns, brownfield ≤4**. One repair cycle adds ≤2. + +> **Tool vocabulary.** Tool names use Claude Code conventions: `Edit` = in-place string replacement, `Write` = full-file write, `Read`/`Glob`/`Grep` = file read/search, `Bash` = shell. On another harness, map each to its equivalent. Harness cannot emit parallel tool calls → keep the same per-turn grouping as consecutive calls; the CLI chains still collapse round-trips. + +## Source precedence — every activity you author + +1. **Card** — [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md) +2. **Agent memory** — validated snippet from a prior session (see [§ Cross-session memory](#cross-session-memory)) +3. **Rule 21 triple** — `activities find` → `.md` read → `get-default-xaml`, fanned out inside T1/T2 + +`validate` + `build` gate all three. Card/memory hits skip discovery, never the gate. + +## Sequential gates — never batch across these + +- `templates search` → `init` (Rule 2): runs only when the user names a template or domain pattern; its result (possibly an `AskUserQuestion`) picks `--template-package-id`. +- Rule 2a framework/language question when the request carries no signal. +- Any `AskUserQuestion` or consent gate. +- UIA capture (Rule 7) — out of map scope entirely; UIA journeys keep their own flow. + +## Journey: Greenfield XAML (no UIA) + +Skip the project-discovery subagent — no project exists (SKILL.md § Precondition). Write `project-context.md` + `AGENTS.md` yourself at T4. + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Scaffold + context** | ONE `Bash` chain: `uip rpa init --name "" --location "" --template-id BlankTemplate --expression-language --target-framework --output json` (Rule 2a — both flags explicit) `&&` `uip rpa analyzer-rules list --project-dir "" --output json` `&&` one `uip rpa packages versions --package-id --include-prerelease --project-dir "" --output json` per request-known package ∥ parallel `Read`: [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md), [xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md) (Rule 22) ∥ memory recall (harness has memory) ∥ Rule 21 `activities find` fan-out for off-card activities | +| **T2 — Author + install** | One `Write` per workflow file — complete, all activities (Rule 18) ∥ `Read` `project.json` (anchors for the T2/T3 edits; skip re-reading scaffolded `Main.xaml` — the `Write` replaces it) ∥ `Edit` `project.json` (`fileInfoCollection` for test cases, Rule 10; `dependencies` stays CLI-owned via `packages install`) ∥ ONE `Bash`: `uip rpa packages install --packages 'id=,version=' --project-dir "" --output json` per package ∥ Rule 21 doc `Read`s + `get-default-xaml` for off-card activities | +| **T3 — Gate** | ONE `Bash`: `uip rpa validate --file-path "" --project-dir "" --output json` per file `&&` `uip rpa build "" --output json`. `--file-path` RELATIVE to project dir — absolute paths falsely fail (separator bug, [cli-reference.md § validate](cli-reference.md#validate)) | +| **T4 — Report** | § Completion Output + write `project-context.md`/`AGENTS.md` + memory save ([§ Cross-session memory](#cross-session-memory)) | + +- First chain call pays the cold Helm restore (30–90 s) — the chain hides it behind one turn; do not split to "check progress". +- `init` can return `success: false` yet create files (partial success) — before retrying, check `project.json` exists ([environment-setup.md](environment-setup.md)). +- Dependencies land via `packages install` only — never hand-edit `project.json` `dependencies`. + +**Repair cycle (validate/build failure):** one turn — `Edit` fixes by error category (Rule 19); next turn — re-run the T3 chain. >2 errors with ambiguous origin → bisect: stub out half the new activities, re-validate. Caps: 5 attempts per loop (Rule 3). + +## Journey: Brownfield XAML edit + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Context** | § Precondition context check ∥ `Read` `project.json` + target `.xaml` + cards ∥ ONE `Bash`: `analyzer-rules list --project-dir "" --output json` ∥ memory recall ∥ off-card `activities find` fan-out | +| **T2 — Edit** | Batched `Edit`s (anchor each on its own target block — same-file Edits serialize; overlapping anchors fail) ∥ `packages install` `Bash` if new dependencies | +| **T3 — Gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` | +| **T4 — Report** | § Completion Output + memory save | + +## Journey: Greenfield coded + +`init` always scaffolds XAML — same command as above; coded mode = add `.cs` files after ([environment-setup.md](environment-setup.md)). + +| Turn | Emit in ONE assistant message | +|---|---| +| **T1 — Scaffold + context** | ONE `Bash` chain: `init` (flags as XAML journey) `&&` `analyzer-rules list` `&&` `packages versions` per known package ∥ `Read` [assets/codedworkflow-template.md](../assets/codedworkflow-template.md) + [coded/coding-guidelines.md](coded/coding-guidelines.md) ∥ memory recall | +| **T2 — Author + install** | `Write` each `.cs` (Rules 13–19) ∥ `Read` `project.json` ∥ `Edit` `project.json` (`entryPoints` Rule 15, `fileInfoCollection` Rule 10) ∥ `packages install` `Bash` ∥ `Read` `.local/docs/packages//coded/coded-api.md` for installed services | +| **T3 — Gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` | +| **T4 — Report** | § Completion Output + memory save | + +## Journey: Brownfield coded edit + +Brownfield XAML journey with coded reads: T1 `Read` target `.cs` + `.local/docs/.../coded/coded-api.md` for touched services; T2 `Edit`s ∥ install; T3 gate; T4 report. + +## Failure exits + +| Symptom | Open | +|---|---| +| `validate` structural/reference errors | [validation-guide.md](validation-guide.md) | +| XAML activity gotcha (property conflicts, scope) | [xaml/common-pitfalls.md](xaml/common-pitfalls.md) | +| Coded `CS*` errors | [coded/coding-guidelines.md § Common Issues](coded/coding-guidelines.md) | +| CLI error (`timeout`, `EPIPE`, `401`, `not in the project folder`) | [cli-reference.md § CLI Error Recovery](cli-reference.md#cli-error-recovery) | +| Card snippet rejected by validate/build | Fall back to Rule 21 triple for that activity; report stale entry via `/uipath-feedback` | +| Anything UIA | Rule 7 flow — leave this map | + +## Cross-session memory + +Harness-conditional: engage only when the harness provides persistent memory; otherwise skip silently. + +**Recall — T1 of every journey.** Match saved entries by activity class + package `major.minor`. Hit ⇒ that activity skips the Rule 21 triple. `validate`/`build` still gate. + +**Save — after project `build` is clean (T4).** Save only: + +1. Validated XAML snippet per off-card activity — key: activity class + package `major.minor` + date. +2. Error→root-cause→fix triples that cost >1 validate attempt. +3. Cross-version package gotchas. + +**Never save:** project-specific facts (paths, asset names, connections — belong in `project-context.md`), anything UIA (selectors/targets are per-app), secrets. + +**Expiry:** recalled snippet fails validation → delete/overwrite that entry, fall back to Rule 21 triple. From 5d55bf35aee09cc6c1bc763b43fe21a8506eff62 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 14:44:53 +0300 Subject: [PATCH 04/10] feat(uipath-rpa): route builds through execution maps; batch-author with single validate gate Rule 18 rewritten (batch-author), Call Batching section replaced by Execution Maps pointer, Rule 21 gains pattern-card + memory precedence, greenfield skips the discovery subagent, completion saves memory patterns. workflow-guide.md and environment-setup.md aligned. Co-Authored-By: Claude Fable 5 --- skills/uipath-rpa/SKILL.md | 30 +++++++------------ .../references/environment-setup.md | 2 +- .../references/xaml/workflow-guide.md | 10 +++---- 3 files changed, 16 insertions(+), 26 deletions(-) diff --git a/skills/uipath-rpa/SKILL.md b/skills/uipath-rpa/SKILL.md index 08eaa7451c..7e6f5b68f6 100644 --- a/skills/uipath-rpa/SKILL.md +++ b/skills/uipath-rpa/SKILL.md @@ -36,7 +36,7 @@ Before doing any work, check if `.claude/rules/project-context.md` exists in the 6. If **any individual count differs by 60–70% or more** → run the discovery flow below 7. If all counts are within the threshold → context is fresh, proceed with the skill workflow -**If the file does NOT exist** → run the discovery flow below. +**If the file does NOT exist** → if a `project.json` exists, run the discovery flow below. **Greenfield (no `project.json`): skip the discovery agent** — nothing to discover. After the build completes, write both context files yourself (step 3 below) from what you just created: structure, dependencies, entry points. **Discovery flow** (used for both missing and stale context): 1. Spawn the project discovery agent and wait for it to complete. Its definition lives inside this skill at [`agents/uipath-project-discovery-agent.md`](agents/uipath-project-discovery-agent.md). Use whichever spawn mechanism your host supports: @@ -157,7 +157,7 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 & - **Smoke-test shortcut:** A successful `uip rpa run` substitutes for the standalone end-of-session `build` — `run` compiles internally. Prefer `run --skip-build` when `build` has just passed; see [validation-guide.md § Smoke Test](references/validation-guide.md). See [references/validation-guide.md](references/validation-guide.md). -4. **ALWAYS validate files as you go AND verify the project builds before declaring done.** After every create or edit: per-file `validate` to clean. Project-level `build` runs once at the end of the edit session (or at any compile-verification gate) — not after every Edit, because `build` is project-scoped and rebuilds the entire project regardless of which file changed. `validate` clean alone is not "validated"; it cannot see member or enum errors — the project-level `build` is mandatory before declaring done. See [references/validation-guide.md](references/validation-guide.md). +4. **ALWAYS bring every touched file to per-file `validate` clean AND verify the project builds before declaring done.** Cadence per Rule 18: batch-author, then validate. Project-level `build` runs once at the end of the edit session (or at any compile-verification gate) — not after every Edit, because `build` is project-scoped and rebuilds the entire project regardless of which file changed. `validate` clean alone is not "validated"; it cannot see member or enum errors — the project-level `build` is mandatory before declaring done. See [references/validation-guide.md](references/validation-guide.md). 5. **Prefer UiPath built-in activities** for Orchestrator integration, UI automation, and document handling. Prefer plain .NET / third-party packages for pure data transforms, HTTP calls, parsing. 6. **ALWAYS ensure required package dependencies are in `project.json`** before using their activities or services. 6a. **Pre-edit verification gate.** Two authoring actions are hard to roll back once `build` fails — verify before serialization, not after. @@ -199,24 +199,11 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 & - "Feels expensive", "many tool calls used", "natural pause point", "partial result looks usable", and "too complex to continue in one session" are **NOT** Stop conditions. Only the concrete hard blockers in the plan's `Stop conditions` section count. - Plan decisions already made are authoritative. Do not `AskUserQuestion` about structure, file count, selector strategy, or capture approach when the plan specifies them — those questions belonged to the planner. -### Call Batching (Both Modes) +### Execution Maps (Both Modes) -**Batch independent tool calls into one assistant message — minimize model round-trips.** Two points in a new-project build serialize needlessly by default; collapse each into a single message. +**Follow the journey map in [execution-maps-guide.md](references/execution-maps-guide.md) for every build or edit** — it fixes which tool calls batch into which assistant turn (greenfield ≤5 turns, brownfield ≤4). Within a turn: chain dependent `uip` calls with `&&` in one `Bash`; emit independent `Bash`/`Read`/`Edit` calls as parallel tool uses. Split turns only where a call needs an earlier call's stdout or a file mutation. Rule 21 discovery for off-card activities fans out inside T1/T2 — all K `find`s parallel, then all K doc `Read`s, then all K `get-default-xaml`s — never one activity at a time. -1. **Post-`init` prerequisite batch.** After `uip rpa init` returns, these depend only on the project existing — NOT on each other. Emit them in ONE message: - - `Read` `project.json` + the scaffolded `Main.xaml` - - `uip rpa analyzer-rules list` (Rule 3 authoring-phase prerequisite) - - `uip rpa packages install` for packages already known from the request - - `uip rpa activities find` for activities you'll author - - These share the warmed Studio host (§ Session Pre-warm) — pay the cold-start once, then fire the batch. -2. **Activity-discovery fan-out.** Rule 21 runs a triple per non-card activity (`activities find` → read `.md` → `get-default-xaml`). For K activities, emit all K `find`s as parallel `Bash`, then all K doc `Read`s in parallel, then all K `get-default-xaml`s in parallel — never one activity at a time. See [xaml/workflow-guide.md § Phase 1](references/xaml/workflow-guide.md). - -**Chaining:** chain dependent `uip` calls with `&&` in one `Bash`; emit independent `Bash` / `Read` calls as parallel tool uses. Split a turn only where a call needs an earlier call's stdout or a file mutation. - -**Do NOT batch — sequential by design:** -- `templates search` → `init`. The search result (and possibly an `AskUserQuestion`) picks `--template-package-id` (Rule 2). Decision gate, not a chain. -- The **per-file `validate` / per-activity authoring loop** (Rule 4, XAML Rule 18). Build one activity at a time, validate after each; project-level `build` runs once at the end. Batching validation hides which activity broke and burns the 5-attempt cap (Rule 3). +**Sequential by design — never batch across:** `templates search` → `init` (Rule 2 decision gate); any `AskUserQuestion` or consent gate; UIA capture flows (Rule 7). ### Coded-Specific Rules @@ -232,11 +219,11 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 & 16. **[XAML] Activity docs are the source of truth** — check `{projectRoot}/.local/docs/packages/{PackageId}/` first. Always. 17. **[XAML] MUST understand project structure** — read `project.json`, check expression language, scan existing patterns. NEVER generate XAML blind. -18. **[XAML] Start minimal, iterate to correct** — build one activity at a time, validate after each addition. +18. **[XAML] Batch-author, single gate** — author the complete workflow in one pass, sourcing each activity card → memory → Rule 21 triple (precedence in [execution-maps-guide.md](references/execution-maps-guide.md)). Then per-file `validate` to clean, then one project `build` (Rule 3 cadence, 5-attempt caps unchanged). On failure: fix by error category (Rule 19); >2 errors with ambiguous origin → bisect (stub out half the new activities, re-validate). 19. **[XAML] Fix errors by category** — Package → Structure → Type → Activity Properties → Logic. 20. **[XAML] Flowchart node structure + ViewState both decide whether a Flowchart renders.** **Structure first:** every `FlowStep`/`FlowDecision`/`FlowSwitch` MUST be a direct child of `` (only direct children are added to the `Flowchart.Nodes` collection), wired through `Flowchart.StartNode`/`FlowStep.Next`/branches with ``+`x:Name`. NEVER build the flow as a nested chain — one `FlowStep` physically nested inside the previous one's `` — because nested-only steps are absent from `Flowchart.Nodes` and the designer renders almost nothing, regardless of ViewState. **Then ViewState:** when generating new Flowchart/StateMachine/ProcessDiagram workflows, per-node ViewState is MANDATORY — `ShapeLocation`+`ShapeSize` on every node (`ConnectorLocation` optional, Studio auto-routes). Without it Studio stacks every node at (0,0) so they overlap into what looks like a single node, and Studio does NOT auto-arrange on open (see [canvas-layout-guide.md](references/xaml/canvas-layout-guide.md)). When editing existing files, do NOT modify ViewState on nodes you are not changing. For Sequences, ViewState is optional. 21. **[XAML] Reading `.md` from `{PROJECT_DIR}/.local/docs/packages/...` is a precondition for `activities get-default-xaml` — for every activity not on the common-activity card.** - - **Card-listed activities:** check [references/common-activity-card.md](references/common-activity-card.md) first; if the activity is on the card, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read. + - **Card-listed activities and patterns:** check [references/common-activity-card.md](references/common-activity-card.md) and [references/common-pattern-card.md](references/common-pattern-card.md) first; on a card hit, author from the card entry alone — skip `activities find`, skip `activities get-default-xaml`, skip the per-activity MD read. Precedence: card → agent memory ([execution-maps-guide.md § Cross-session memory](references/execution-maps-guide.md#cross-session-memory)) → full triple. A memory hit substitutes for the triple only; `validate`/`build` still gate. - **All other activities:** (1) `activities find` → class name, (2) **read `.md` first** and extract a property checklist (required + use-case-relevant), (3) `activities get-default-xaml` → starter element, (4) **diff your checklist against the starter and add what's missing** — an empty checklist means you skipped step 2, go back. - **Doc lookup order:** primary `{PROJECT_DIR}/.local/docs/packages//activities/.md`; fallback `references/activity-docs///.md` for older package versions where `.local/docs` is empty. **Exception — `UiPath.UIAutomation.Activities` has no bundled fallback:** `.local/docs` (present only after the package is installed) is its sole activity-doc source. If it is absent, do not hunt for a bundled copy — follow Rule 7a (install with consent per [uia-prerequisites.md](references/uia-prerequisites.md), or use the Placeholder-Selector Stub Pattern). - **Trigger activities are special — read BOTH docs.** When the class name ends in `Trigger`, the namespace contains `.Triggers`, or the description mentions "starts a job" / "Monitor Events" / "Trigger Scope", also read the bundled `references/activity-docs///activities/.md` **and** the package's bundled `overview.md`. The auto-generated `.local/docs` version is sparse for triggers; the bundled hand-written docs carry placement guidance (entry-point vs. `ui:TriggerScope`), deployment context, and cross-cutting namespace/assembly gotchas that the extractor does not capture. See Common Rule 12 and [trigger-pattern-guide.md](references/trigger-pattern-guide.md). @@ -253,6 +240,7 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 & | I need to... | Mode | Read these | |-------------|------|-----------| | **Work in a Legacy (.NET 4.6.1) project** | Legacy | [legacy/legacy-mode-guide.md](references/legacy/legacy-mode-guide.md) — entry point. Modern-mode rules below do not apply. | +| **Plan the build's turn structure** | Both | [execution-maps-guide.md](references/execution-maps-guide.md) — read first for any build/edit journey | | **Choose coded vs XAML** | Both | [coded-vs-xaml-guide.md](references/coded-vs-xaml-guide.md) | | **Work in a hybrid project** | Hybrid | [coded-vs-xaml-guide.md](references/coded-vs-xaml-guide.md) → [project-structure.md](references/project-structure.md) | | **Create a new project** | Both | [environment-setup.md](references/environment-setup.md) | @@ -465,6 +453,8 @@ UIA references live in two locations. Always cite by location so the reader know 3. If unchecked boxes remain because a Stop condition was hit, name the exact stop-condition item in the report. 4. If the plan is fully checked off, or execution autonomy is `interactive`, proceed to the report format below. +Then, if the harness provides persistent memory, save validated patterns per [execution-maps-guide.md § Cross-session memory](references/execution-maps-guide.md#cross-session-memory) before reporting. + When you finish a task, report to the user: 1. **What was done** — files created, edited, or deleted (list file paths) 2. **Validation status** — per-file `validate` result (all files passed, or remaining errors) **and** project-level `uip rpa build` result. Both must be clean to claim verification — `validate` clean alone is insufficient (it does not detect unknown member names or invalid enum values). If `build` has not run since the last edit, say so explicitly rather than claiming success. diff --git a/skills/uipath-rpa/references/environment-setup.md b/skills/uipath-rpa/references/environment-setup.md index 538b63f88d..df3bc3f124 100644 --- a/skills/uipath-rpa/references/environment-setup.md +++ b/skills/uipath-rpa/references/environment-setup.md @@ -171,7 +171,7 @@ Pass `--target-framework` and `--expression-language` here too (Rule 2a) — a t 2. **Read the scaffolded files** — the command generates starter files. Read them before making changes so you build on valid defaults 3. Proceed with the skill workflow using the new project root -> **Batch the post-`init` prerequisites.** Step 2 here, the analyzer-rules list (SKILL.md Rule 3), `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Call Batching. +> **Batch the post-`init` prerequisites.** Step 2 here, the analyzer-rules list (SKILL.md Rule 3), `packages install` for known-needed packages, and the first `activities find` all depend only on the project existing — emit them as parallel tool calls in one message, not one per turn. They share the warmed Studio host. See SKILL.md § Execution Maps and [execution-maps-guide.md](execution-maps-guide.md). ## Edge case: requiring Studio Desktop diff --git a/skills/uipath-rpa/references/xaml/workflow-guide.md b/skills/uipath-rpa/references/xaml/workflow-guide.md index 72c9bde0a8..8ef6e29b79 100644 --- a/skills/uipath-rpa/references/xaml/workflow-guide.md +++ b/skills/uipath-rpa/references/xaml/workflow-guide.md @@ -1,14 +1,14 @@ # XAML Workflow Guide -Discovery-first approach with iterative error-driven refinement for generating and editing XAML workflows. Always understand before acting, start simple, and validate continuously. +Discovery-first approach for generating and editing XAML workflows. Always understand before acting, author complete, and gate with `validate` + `build`. ## Core Principles 1. **Activity Docs Are the Source of Truth** — Installed packages may ship structured documentation at `{projectRoot}/.local/docs/packages/{PackageId}/`. When present, these docs contain source-accurate properties, types, defaults, enum values, conditional property groups, and working XAML examples. Always check for them first. 2. **Know Before You Write** — **NEVER** generate XAML blind. Understand the project structure, packages, expression language, and existing patterns. 3. **Use What You Know, Skip What You Don't Need** — If you already know the package ID and activity class name, go directly to its doc file. Be efficient: the discovery steps are a priority ladder, not a mandatory checklist. -4. **Start Minimal, Iterate to Correct** — Start one workflow at a time and break out logic into multiple files if needed. Build one activity at a time within each workflow. Write the smallest working XAML, validate with `uip rpa validate`, fix what breaks, repeat. -5. **Validate After Every Change** — **MUST** validate with **both** `validate` and `uip rpa build` after every change. **NEVER** assume an edit succeeded. `validate` clean alone is not validated — it does not catch unknown member names or invalid enum values; `build` does. +4. **Batch-Author, Single Gate** — One workflow at a time; break logic into multiple files if needed. Author each workflow complete in one pass (SKILL.md Rule 18; source activities card → memory → discovery triple), then per-file `validate` to clean, fixing by category. +5. **Gate Before Done** — **MUST** bring every changed file to per-file `validate` clean AND the project through `uip rpa build` before declaring done. **NEVER** assume an edit succeeded. `validate` clean alone is not validated — it does not catch unknown member names or invalid enum values; `build` does. 6. **Fix Errors by Category** — Triage in order: Package → Structure → Type → Activity Properties → Logic. --- @@ -28,7 +28,7 @@ If unclear which file to edit, **ask the user** rather than guessing. **Goal:** Understand project context, leverage installed activity documentation, study existing patterns, identify reusable components, and discover activities before writing any XAML. -> **Batch discovery across activities.** When the workflow needs several activities, do NOT run the find → read-doc → `get-default-xaml` triple one activity at a time. Emit all `activities find` calls in parallel, then all `.md` `Read`s in parallel, then all `get-default-xaml` calls in parallel (SKILL.md § Call Batching). Only the per-activity *authoring + validate* loop (Phase 2 / Phase 3) stays sequential — discovery fans out. +> **Batch discovery across activities.** When the workflow needs several activities, do NOT run the find → read-doc → `get-default-xaml` triple one activity at a time. Emit all `activities find` calls in parallel, then all `.md` `Read`s in parallel, then all `get-default-xaml` calls in parallel (SKILL.md § Execution Maps). Authoring batches too — one complete `Write` per workflow (Rule 18), then the Phase 3 gate. ### Step 1.1: Project Structure @@ -173,7 +173,7 @@ Before writing any XAML with UI activities: [ui-automation-guide.md](../ui-autom ### For CREATE Requests -**Strategy:** Generate minimal working version, one activity at a time, validate frequently. +**Strategy:** Author the complete workflow in one `Write` (SKILL.md Rule 18), then gate via Phase 3. Use the `Write` tool to create a new `.xaml` file. Refer to [xaml-basics-and-rules.md](xaml-basics-and-rules.md) for the complete XAML file anatomy template. From e2a7975753bb78328a5194167392fc03889a50fe Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 14:59:25 +0300 Subject: [PATCH 05/10] =?UTF-8?q?feat(uipath-rpa):=20pattern=20card=20batc?= =?UTF-8?q?h=201=20=E2=80=94=20six=20System-package=20patterns,=20CLI-veri?= =?UTF-8?q?fied=20on=2026.6.1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All snippets validate+build clean on a Portable/VB scratch project. Build-verified traps encoded as Notes: BuildDataTable is Windows-only, ParsingMethod is designer-only (runtime: CSVParsing), ArrayRow needs s:Object[], DataTable group needs clr-namespace xmlns form. Queue consume loop dropped: GetTransactionItem absent cross-platform. Co-Authored-By: Claude Fable 5 --- .../references/common-pattern-card.md | 225 ++++++++++++++++++ .../references/execution-maps-guide.md | 2 +- 2 files changed, 226 insertions(+), 1 deletion(-) create mode 100644 skills/uipath-rpa/references/common-pattern-card.md diff --git a/skills/uipath-rpa/references/common-pattern-card.md b/skills/uipath-rpa/references/common-pattern-card.md new file mode 100644 index 0000000000..9cf91f84dd --- /dev/null +++ b/skills/uipath-rpa/references/common-pattern-card.md @@ -0,0 +1,225 @@ +# Common Pattern Card + +**Package anchor:** `UiPath.System.Activities` 26.6.1 — every entry CLI-verified (`uip rpa validate` + `uip rpa build` clean) on a `Portable` (cross-platform) / VisualBasic project. Modern Windows-target projects use the same assembly names (`System.Private.CoreLib`); Legacy (.NET 4.6.1) projects are NOT covered. + +Copy-safe multi-activity snippets. **Supersedes the Rule 21 discovery procedure for every activity inside a listed pattern.** For activities outside these patterns, Rule 21 applies. Precedence: card → agent memory → Rule 21 triple ([execution-maps-guide.md](execution-maps-guide.md)). If `validate`/`build` rejects a card snippet: fall back to the Rule 21 triple for that activity and report the stale entry via `/uipath-feedback`. + +## Card entries + +Text file read/append/write · File ops guarded copy · DataTable generate→filter→CSV · Queue publish · Retry wrap · Invoke workflow with arguments + +## How to read the snippets + +Snippets are complete `` fragments (with their `Variables`) for a root `` whose xmlns set matches the scaffolded `Main.xaml` (`uip rpa init` output) — keep its `TextExpression.NamespacesForImplementation` / `ReferencesForImplementation` blocks. Root prefixes used below: + +```xml +xmlns:ui="http://schemas.uipath.com/workflow/activities" +xmlns:uic="clr-namespace:UiPath.Core.Activities;assembly=UiPath.System.Activities" +xmlns:s="clr-namespace:System;assembly=System.Private.CoreLib" +xmlns:sd="clr-namespace:System.Data;assembly=System.Data.Common" +xmlns:scg="clr-namespace:System.Collections.Generic;assembly=System.Private.CoreLib" +``` + +Each entry lists which of these it needs. VB expression form (`[expr]` attributes); C# projects: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md). + +> **Why two UiPath prefixes:** some activities (`BuildDataTable` — Windows-only, and by extension the DataTable group) are not registered under the `http://schemas.uipath.com/workflow/activities` URI on cross-platform assemblies. The `uic:` clr-namespace form resolves whenever the type is loadable. File/queue/retry/invoke activities verified fine under `ui:`. + +--- + +### Text file read / append / write +**Activities:** `UiPath.Core.Activities.ReadTextFile` · `AppendLine` · `WriteTextFile` +**Prefixes:** `ui:` +**Variables:** `fileContent : String` — file text; `logEntry : String` — line to append. + +```xml + + + + + + + + + +``` + +**Notes:** `WriteTextFile` overwrites; `AppendLine` preserves content and creates the file if missing. `Encoding` `null` = auto-detect (read) / system default (write). `FileName` literal or `[expr]`. +**Long-form:** [`ReadTextFile.md`](activity-docs/UiPath.System.Activities/26.4/activities/ReadTextFile.md) · [`WriteTextFile.md`](activity-docs/UiPath.System.Activities/26.4/activities/WriteTextFile.md) · AppendLine: `{PROJECT_DIR}/.local/docs/packages/UiPath.System.Activities/activities/AppendLine.md` + +--- + +### File ops — guarded copy +**Activities:** `UiPath.Core.Activities.PathExists` · `CreateDirectory` · `CopyFile` (+ built-in `If`) +**Prefixes:** `ui:` +**Variables:** `fileExists : Boolean`. + +```xml + + + + + + + + + + + + + + + + + + + +``` + +**Notes:** `PathType="File"` makes a directory at that path return `Exists=False`. `CreateDirectory` is idempotent and creates intermediate dirs. `CopyFile` into an existing folder keeps the name; a full-file destination requires the parent to exist. `MoveFile`/`Delete` share the same `Path` shape. +**Long-form:** [`PathExists.md`](activity-docs/UiPath.System.Activities/26.4/activities/PathExists.md) · [`CopyFile.md`](activity-docs/UiPath.System.Activities/26.4/activities/CopyFile.md) · [`CreateDirectory.md`](activity-docs/UiPath.System.Activities/26.4/activities/CreateDirectory.md) + +--- + +### DataTable — generate → add row → filter → CSV text +**Activities:** `UiPath.Core.Activities.GenerateDataTable` · `AddDataRow` · `FilterDataTable` · `OutputDataTable` +**Prefixes:** `uic:`, `sd:`, `scg:`, `s:` +**Variables:** `dt, filteredDt : System.Data.DataTable`; `csvText : String`. + +```xml + + + + + + + + + ["Name,Age" & vbLf & "Bob,25"] + + + [dt] + + + + + [dt] + + + [New Object() {"Alice", 30}] + + + + + [dt] + + + + + + "Age" + + + [10] + + + + + + + + [filteredDt] + + + [csvText] + + + +``` + +**Notes (build-verified traps):** `BuildDataTable` does NOT load on cross-platform projects (`TypeLoadException`) — generate from CSV text instead. `ParsingMethod`/`CSV` from the docs is designer-only; the runtime member is `CSVParsing="True"`. `ArrayRow` type argument must be `s:Object[]` — `x:Object[]` fails at `build` (not `validate`). `Filters` `Operator` takes enum identifiers (`GT`, `EQ`, `CONTAINS`, …); omit `Operand` for `EMPTY`/`NOTEMPTY`. `AddDataRow.DataTable` is `InOutArgument` — bind a variable, never an expression. +**Long-form:** [`GenerateDataTable.md`](activity-docs/UiPath.System.Activities/26.4/activities/GenerateDataTable.md) · [`AddDataRow.md`](activity-docs/UiPath.System.Activities/26.4/activities/AddDataRow.md) · [`FilterDataTable.md`](activity-docs/UiPath.System.Activities/26.4/activities/FilterDataTable.md) · [`OutputDataTable.md`](activity-docs/UiPath.System.Activities/26.4/activities/OutputDataTable.md) + +--- + +### Queue publish +**Activities:** `UiPath.Core.Activities.AddQueueItem` +**Prefixes:** `ui:`, `s:` + +```xml + + + "INV-2024-002" + 1500.0 + True + [DateTime.Today] + + +``` + +**Notes:** Runtime needs Orchestrator + an existing queue (`QueueType` does not auto-create; 404 error code 1002 otherwise). Use `s:DateTime`, not `x:DateTime`. Item lands with status **New**. Queue **consumption** (`GetTransactionItem`) is not available in cross-platform `UiPath.System.Activities` — for transaction loops see [reframework-guide.md](reframework-guide.md). +**Long-form:** [`AddQueueItem.md`](activity-docs/UiPath.System.Activities/26.4/activities/AddQueueItem.md) + +--- + +### Retry wrap +**Activities:** `UiPath.Core.Activities.RetryScope` +**Prefixes:** `ui:`, `s:` +**Variables:** `fetchedContent : String` (example body output). + +```xml + + + + + + + + + + + + + + + + + + + + + + +``` + +**Notes:** Empty `ActivityFunc` = retry on exception only (the common wrap). To retry-until-true, place an `Activity(Of Boolean)` inside `Condition`. Body serializes as `ActivityBody`/`ActivityAction` — not a bare child. +**Long-form:** [`RetryScope.md`](activity-docs/UiPath.System.Activities/26.4/activities/RetryScope.md) + +--- + +### Invoke workflow with arguments +**Activities:** `UiPath.Core.Activities.InvokeWorkflowFile` +**Prefixes:** `ui:`, `scg:` +**Variables:** `childResult : String`. + +```xml + + + + ["hello"] + [childResult] + + + +``` + +Child workflow declares its contract via root `x:Members`: + +```xml + + + + +``` + +**Notes:** Keys must match the child's declared argument names exactly; `InArgument`/`OutArgument`/`InOutArgument` per direction. Runs synchronously. `WorkflowFileName` is project-relative. XML-escape `&` in VB concatenation (`&`). +**Long-form:** [`InvokeWorkflow.md`](activity-docs/UiPath.System.Activities/26.4/activities/InvokeWorkflow.md) diff --git a/skills/uipath-rpa/references/execution-maps-guide.md b/skills/uipath-rpa/references/execution-maps-guide.md index 5fdf0ab467..ae60a082a3 100644 --- a/skills/uipath-rpa/references/execution-maps-guide.md +++ b/skills/uipath-rpa/references/execution-maps-guide.md @@ -26,7 +26,7 @@ Skip the project-discovery subagent — no project exists (SKILL.md § Precondit | Turn | Emit in ONE assistant message | |---|---| | **T1 — Scaffold + context** | ONE `Bash` chain: `uip rpa init --name "" --location "" --template-id BlankTemplate --expression-language --target-framework --output json` (Rule 2a — both flags explicit) `&&` `uip rpa analyzer-rules list --project-dir "" --output json` `&&` one `uip rpa packages versions --package-id --include-prerelease --project-dir "" --output json` per request-known package ∥ parallel `Read`: [common-activity-card.md](common-activity-card.md), [common-pattern-card.md](common-pattern-card.md), [xaml/xaml-basics-and-rules.md](xaml/xaml-basics-and-rules.md) (Rule 22) ∥ memory recall (harness has memory) ∥ Rule 21 `activities find` fan-out for off-card activities | -| **T2 — Author + install** | One `Write` per workflow file — complete, all activities (Rule 18) ∥ `Read` `project.json` (anchors for the T2/T3 edits; skip re-reading scaffolded `Main.xaml` — the `Write` replaces it) ∥ `Edit` `project.json` (`fileInfoCollection` for test cases, Rule 10; `dependencies` stays CLI-owned via `packages install`) ∥ ONE `Bash`: `uip rpa packages install --packages 'id=,version=' --project-dir "" --output json` per package ∥ Rule 21 doc `Read`s + `get-default-xaml` for off-card activities | +| **T2 — Author + install** | One `Write` per workflow file — complete, all activities (Rule 18) ∥ `Read` `project.json` (anchors for the T2/T3 edits; skip re-reading scaffolded `Main.xaml` — the `Write` replaces it) ∥ `Edit` `project.json` (`fileInfoCollection` for test cases, Rule 10; `dependencies` stays CLI-owned via `packages install`) ∥ ONE `Bash`: `uip rpa packages install` for all needed packages at the T1-chosen versions — flag shape per [cli-reference.md § packages install](cli-reference.md#packages-install); it drifts across CLI builds, so on `Invalid packages input` re-check `uip rpa packages install --help` ∥ Rule 21 doc `Read`s + `get-default-xaml` for off-card activities | | **T3 — Gate** | ONE `Bash`: `uip rpa validate --file-path "" --project-dir "" --output json` per file `&&` `uip rpa build "" --output json`. `--file-path` RELATIVE to project dir — absolute paths falsely fail (separator bug, [cli-reference.md § validate](cli-reference.md#validate)) | | **T4 — Report** | § Completion Output + write `project-context.md`/`AGENTS.md` + memory save ([§ Cross-session memory](#cross-session-memory)) | From f5e34a56320583fe08fce7020e690be72e35053b Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 15:05:35 +0300 Subject: [PATCH 06/10] =?UTF-8?q?feat(uipath-rpa):=20pattern=20card=20batc?= =?UTF-8?q?h=202=20=E2=80=94=20CSV=20and=20HTTP=20patterns,=20CLI-verified?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Excel X family and SMTP SendMail deliberately excluded: Platform: Windows only per their docs, TypeLoadException on the cross-platform gate — card notes route them to Rule 21 on Windows targets. HTTP entry teaches modern NetHttpRequest (HttpClient is legacy) and the UiPath.Web.Activities assembly-name trap. Co-Authored-By: Claude Fable 5 --- .../references/common-pattern-card.md | 58 ++++++++++++++++++- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/skills/uipath-rpa/references/common-pattern-card.md b/skills/uipath-rpa/references/common-pattern-card.md index 9cf91f84dd..f823b25e99 100644 --- a/skills/uipath-rpa/references/common-pattern-card.md +++ b/skills/uipath-rpa/references/common-pattern-card.md @@ -1,12 +1,14 @@ # Common Pattern Card -**Package anchor:** `UiPath.System.Activities` 26.6.1 — every entry CLI-verified (`uip rpa validate` + `uip rpa build` clean) on a `Portable` (cross-platform) / VisualBasic project. Modern Windows-target projects use the same assembly names (`System.Private.CoreLib`); Legacy (.NET 4.6.1) projects are NOT covered. +**Package anchors:** `UiPath.System.Activities` 26.6.1 · `UiPath.Excel.Activities` 3.6.0-preview (CSV group) · `UiPath.WebAPI.Activities` 2.5.1 — every entry CLI-verified (`uip rpa validate` + `uip rpa build` clean) on a `Portable` (cross-platform) / VisualBasic project. Modern Windows-target projects use the same assembly names (`System.Private.CoreLib`); Legacy (.NET 4.6.1) projects are NOT covered. + +**Not on this card (Windows-only, unverifiable on the cross-platform gate):** Excel X activities (`ExcelProcessScopeX`/`ExcelApplicationCard`/`ReadRangeX`, …) and SMTP `SendMail` — their docs state `Platform: Windows only`; cross-platform assemblies throw `TypeLoadException`. Author via the full Rule 21 triple on a Windows-target project. Copy-safe multi-activity snippets. **Supersedes the Rule 21 discovery procedure for every activity inside a listed pattern.** For activities outside these patterns, Rule 21 applies. Precedence: card → agent memory → Rule 21 triple ([execution-maps-guide.md](execution-maps-guide.md)). If `validate`/`build` rejects a card snippet: fall back to the Rule 21 triple for that activity and report the stale entry via `/uipath-feedback`. ## Card entries -Text file read/append/write · File ops guarded copy · DataTable generate→filter→CSV · Queue publish · Retry wrap · Invoke workflow with arguments +Text file read/append/write · File ops guarded copy · DataTable generate→filter→CSV · Queue publish · Retry wrap · Invoke workflow with arguments · CSV file read/write · HTTP request → JSON ## How to read the snippets @@ -18,6 +20,11 @@ xmlns:uic="clr-namespace:UiPath.Core.Activities;assembly=UiPath.System.Activitie xmlns:s="clr-namespace:System;assembly=System.Private.CoreLib" xmlns:sd="clr-namespace:System.Data;assembly=System.Data.Common" xmlns:scg="clr-namespace:System.Collections.Generic;assembly=System.Private.CoreLib" +xmlns:csv="clr-namespace:UiPath.CSV.Activities;assembly=UiPath.Excel.Activities" +xmlns:nhr="clr-namespace:UiPath.Web.Activities.Http;assembly=UiPath.Web.Activities" +xmlns:nhrm="clr-namespace:UiPath.Web.Activities.Http.Models;assembly=UiPath.Web.Activities" +xmlns:web="clr-namespace:UiPath.Web.Activities;assembly=UiPath.Web.Activities" +xmlns:jn="clr-namespace:Newtonsoft.Json.Linq;assembly=Newtonsoft.Json" ``` Each entry lists which of these it needs. VB expression form (`[expr]` attributes); C# projects: [xaml/csharp-activity-binding-guide.md](xaml/csharp-activity-binding-guide.md). @@ -223,3 +230,50 @@ Child workflow declares its contract via root `x:Members`: **Notes:** Keys must match the child's declared argument names exactly; `InArgument`/`OutArgument`/`InOutArgument` per direction. Runs synchronously. `WorkflowFileName` is project-relative. XML-escape `&` in VB concatenation (`&`). **Long-form:** [`InvokeWorkflow.md`](activity-docs/UiPath.System.Activities/26.4/activities/InvokeWorkflow.md) + +--- + +### CSV file read / write +**Activities:** `UiPath.CSV.Activities.ReadCsvFile` · `AppendWriteCsvFile` +**Packages:** `UiPath.Excel.Activities` 3.6.0-preview (CSV activities are Excel-package-owned, cross-platform, no Excel app needed) +**Prefixes:** `csv:`, `sd:` +**Variables:** `csvData : System.Data.DataTable`. + +```xml + + + + + + + + [csvData] + + + +``` + +**Notes:** `CsvAction`: `Write` replaces, `Append` adds after existing rows. Delimiter via `DelimitatorForViewModel` (`Comma` default; `Semicolon`/`Pipe`/`Caret`/`Tab`). `IncludeColumnNames="True"` = first row is headers. +**Long-form:** [`ReadCsvFile.md` (3.6)](activity-docs/UiPath.Excel.Activities/3.6/activities/ReadCsvFile.md) · `{PROJECT_DIR}/.local/docs/packages/UiPath.Excel.Activities/activities/AppendWriteCsvFile.md` + +--- + +### HTTP request → JSON +**Activities:** `UiPath.Web.Activities.Http.NetHttpRequest` · `UiPath.Web.Activities.DeserializeJson` +**Packages:** `UiPath.WebAPI.Activities` 2.5.1 +**Prefixes:** `nhr:`, `nhrm:`, `web:`, `jn:` +**Variables:** `httpResponse : UiPath.Web.Activities.Http.Models.HttpResponseSummary`; `jsonResult : Newtonsoft.Json.Linq.JObject`. + +```xml + + + + + + + + +``` + +**Notes (build-verified traps):** Use `NetHttpRequest` — `HttpClient` is legacy. The XAML assembly is `UiPath.Web.Activities`, NOT the package id `UiPath.WebAPI.Activities`; `HttpResponseSummary` lives in `...Http.Models`. Read body from `httpResponse.TextContent`, verdict from `httpResponse.StatusCode`. Default `ContinueOnError=True` turns network failures into synthetic `503` responses — guard on `StatusCode` before parsing. POST JSON: `RequestBodyType="Text"` + `TextPayload` (content type defaults to `application/json`). +**Long-form:** `{PROJECT_DIR}/.local/docs/packages/UiPath.WebAPI.Activities/activities/NetHttpRequest.md` · `.../DeserializeJson.md` From abe87d1652b3998420f079ce740759b253b769a7 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 15:06:05 +0300 Subject: [PATCH 07/10] docs(uipath-rpa): pattern card maintenance procedure Co-Authored-By: Claude Fable 5 --- .../.maintenance/pattern-card-maintenance.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 skills/uipath-rpa/.maintenance/pattern-card-maintenance.md diff --git a/skills/uipath-rpa/.maintenance/pattern-card-maintenance.md b/skills/uipath-rpa/.maintenance/pattern-card-maintenance.md new file mode 100644 index 0000000000..e5a2786c81 --- /dev/null +++ b/skills/uipath-rpa/.maintenance/pattern-card-maintenance.md @@ -0,0 +1,20 @@ +# Pattern Card Maintenance + +Regeneration procedure for [references/common-pattern-card.md](../references/common-pattern-card.md). Run when: a stamped package ships a new minor/major, a staleness report arrives (`/uipath-feedback` or repo issue), or a new pattern is added. + +## Procedure + +1. Scratch project (never committed): `uip rpa init --name PatternCard --location --template-id BlankTemplate --expression-language VisualBasic --target-framework Portable --output json`. On macOS/Linux the Helm host cannot open `Windows`-target projects — `Portable` is mandatory there. +2. Install every card-stamped package at the target versions: `uip rpa packages versions --package-id --include-prerelease ...` to pick, then `uip rpa packages install` (flag shape drifts across CLI builds — confirm with `--help`; current builds take a JSON array `[{"id":"...","version":"..."}]`). +3. One probe workflow per card entry: paste the entry's snippet inside a complete `` root cloned from the scaffolded `Main.xaml` (namespaces + `TextExpression` blocks), adding the entry's listed prefixes. +4. Gate: per-file `uip rpa validate --file-path "" --project-dir "" --output json` to 0 errors (relative path — absolute falsely fails), then `uip rpa build "" --output json` clean. `validate` clean is NOT sufficient — namespace-registration and member-name errors surface only at `build`. +5. Failing entry → fix from `{PROJECT_DIR}/.local/docs/packages//activities/.md` (post-install, authoritative for the installed version), re-gate. `Cannot create unknown type` / `TypeLoadException` on a cross-platform gate usually means Windows-only activity → move the entry to the card's "Not on this card" list or validate on a Windows machine before stamping. +6. Update every entry's version stamp + the header package-anchor line. Entries never carry a version they were not gated against. +7. New pattern candidates qualify by frequency: appears in ≥2 `tests/tasks/uipath-rpa/` tasks or is a documented top user ask. Keep the card ≤ ~15 entries — it is a hot-path read, not a catalog. + +## Rules + +- CLI-gate before stamp — no exceptions, no "obviously fine" edits. +- UIA activities never enter this card (`skills/uipath-rpa/CLAUDE.md` boundary). +- Windows-only families (Excel X, SMTP SendMail) require a Windows-target gate; until one runs, they stay off the card with an explicit "Not on this card" note. +- Prose follows `.claude/rules/token-optimization.md`. From 23ee5318d678e51c32ba58bd47659c7656b3ed01 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 15:10:18 +0300 Subject: [PATCH 08/10] test(uipath-rpa): smoke task enforcing execution-map turn budget MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit run_limits.max_turns=10 (comparable pre-map task budgets 36-40 turns). Independent run_command build re-run guards against invocation-only passes; command_not_executed on get-default-xaml asserts the pattern card superseded per-activity discovery. Local coder-eval run pending (no tests/.env credentials in this environment) — must be run and claimed in the PR before merge. Co-Authored-By: Claude Fable 5 --- .../execution_map_greenfield.yaml | 85 +++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 tests/tasks/uipath-rpa/execution_map/execution_map_greenfield.yaml diff --git a/tests/tasks/uipath-rpa/execution_map/execution_map_greenfield.yaml b/tests/tasks/uipath-rpa/execution_map/execution_map_greenfield.yaml new file mode 100644 index 0000000000..1d823d911d --- /dev/null +++ b/tests/tasks/uipath-rpa/execution_map/execution_map_greenfield.yaml @@ -0,0 +1,85 @@ +task_id: skill-rpa-execution-map-greenfield +description: > + Turn-budget gate for the execution-map + pattern-card workflow: a greenfield + cross-platform XAML text-file automation must scaffold, batch-author from the + pattern card (ReadTextFile / AppendLine / LogMessage are all card-covered, so + no per-activity discovery is needed), and pass the validate+build gate within + a hard 10-turn cap. Comparable pre-map task (skill-rpa-xaml-test-case) + budgets 36-40 turns; this task fails if the skill regresses to per-activity + discovery or validate-after-every-activity loops. +tags: [uipath-rpa, smoke, mode:build] + +run_limits: + expected_turns: 6 + max_turns: 10 + turn_timeout: 900 + +sandbox: + driver: tempdir + python: {} + +initial_prompt: | + Build a UiPath XAML automation called "TextReport": read data/orders.txt + (create that input file with a few sample order lines inside the project + first), append a "processed" marker line to it, and log the file contents. + The project must target cross-platform (Portable); Studio Desktop is not + available. The task is not complete until per-file `uip rpa validate` + passes for the workflow AND `uip rpa build` passes for the project. + Use --output json on any uip commands you run. + +success_criteria: + - type: command_executed + description: "Project scaffolded via init with an explicit Portable target framework" + command_pattern: 'uip\s+rpa\s+init\s+.*--target-framework\s+"?Portable"?' + min_count: 1 + weight: 1.0 + pass_threshold: 1.0 + + - type: file_exists + description: "Workflow file exists" + path: "TextReport/Main.xaml" + weight: 1.5 + pass_threshold: 1.0 + + - type: file_contains + description: "Workflow authored with the card-covered activities (read, append, log)" + path: "TextReport/Main.xaml" + includes: + - "ReadTextFile" + - "AppendLine" + - "LogMessage" + weight: 2.0 + pass_threshold: 1.0 + + - type: command_executed + description: "Per-file validate gate ran" + command_pattern: 'uip\s+rpa\s+validate\s+.*--file-path' + min_count: 1 + weight: 1.5 + pass_threshold: 1.0 + + - type: command_executed + description: "Project build gate ran" + command_pattern: 'uip\s+rpa\s+build\b' + min_count: 1 + weight: 1.5 + pass_threshold: 1.0 + + - type: run_command + description: "Project actually compiles — independent build re-run exits 0 (primary validation; a garbage workflow that merely contains the expected strings fails here)" + command: "uip rpa build TextReport --output json" + weight: 3.0 + pass_threshold: 1.0 + + - type: command_not_executed + description: "No per-activity starter-XAML discovery — every activity in this task is card-covered, so get-default-xaml indicates the pattern card was bypassed" + command_pattern: 'uip\s+rpa\s+activities\s+get-default-xaml' + weight: 1.5 + pass_threshold: 1.0 + + - type: command_executed + description: "JSON output discipline on uip calls" + command_pattern: 'uip\s+rpa\s+.*--output\s+json' + min_count: 1 + weight: 1.0 + pass_threshold: 1.0 From 827c9804ab75c651dcd6c1fd41cf958f903f1f3c Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 18:35:56 +0300 Subject: [PATCH 09/10] =?UTF-8?q?feat(uipath-rpa):=20UIA=20journey=20in=20?= =?UTF-8?q?execution=20maps=20=E2=80=94=20author-once-after-capture,=20sin?= =?UTF-8?q?gle=20gate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the UIA capture+build journey at category-pointer level (no package-owned CLI syntax, per skills/uipath-rpa/CLAUDE.md boundary): T0 batches reads/prereqs/baseline/inventory; per-screen capture stays state-gated; authoring defaults to once-after-capture with ONE validate+build gate, superseding validate-after-each-screen-batch in SKILL.md, ui-automation-guide, and uia-configure-target-workflows. Memory protocol now permits process-level UIA lessons; selectors, targets, OR refs, and CLI syntax stay banned. Co-Authored-By: Claude Fable 5 --- skills/uipath-rpa/SKILL.md | 4 ++-- .../references/execution-maps-guide.md | 22 ++++++++++++++++--- .../references/ui-automation-guide.md | 2 +- .../uia-configure-target-workflows.md | 2 +- 4 files changed, 23 insertions(+), 7 deletions(-) diff --git a/skills/uipath-rpa/SKILL.md b/skills/uipath-rpa/SKILL.md index 7e6f5b68f6..9a5b9c98fe 100644 --- a/skills/uipath-rpa/SKILL.md +++ b/skills/uipath-rpa/SKILL.md @@ -203,7 +203,7 @@ uip rpa activities find --query log --output json > /dev/null 2>&1 & **Follow the journey map in [execution-maps-guide.md](references/execution-maps-guide.md) for every build or edit** — it fixes which tool calls batch into which assistant turn (greenfield ≤5 turns, brownfield ≤4). Within a turn: chain dependent `uip` calls with `&&` in one `Bash`; emit independent `Bash`/`Read`/`Edit` calls as parallel tool uses. Split turns only where a call needs an earlier call's stdout or a file mutation. Rule 21 discovery for off-card activities fans out inside T1/T2 — all K `find`s parallel, then all K doc `Read`s, then all K `get-default-xaml`s — never one activity at a time. -**Sequential by design — never batch across:** `templates search` → `init` (Rule 2 decision gate); any `AskUserQuestion` or consent gate; UIA capture flows (Rule 7). +**Sequential by design — never batch across:** `templates search` → `init` (Rule 2 decision gate); any `AskUserQuestion` or consent gate; UIA state advances and indication (the UIA journey in the guide encodes its per-screen gating). ### Coded-Specific Rules @@ -391,7 +391,7 @@ The XAML file anatomy template (namespace declarations, root Activity element, b ### Multi-Screen UI Automation Workflows -For XAML workflows spanning multiple capture screens, add each screen's activities to the workflow as its targets get registered in the OR — validating with `validate` after each batch. [uia-configure-target-workflows.md](references/uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule). +For XAML workflows spanning multiple capture screens, default to author-once-after-capture with a single `validate`+`build` gate (Rule 18); per-screen authoring interleave only on long captures (5+ screens). Full cadence: [ui-automation-guide.md § Multi-Screen Authoring](references/ui-automation-guide.md). [uia-configure-target-workflows.md](references/uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule). ## Resolving Packages & Activity Docs diff --git a/skills/uipath-rpa/references/execution-maps-guide.md b/skills/uipath-rpa/references/execution-maps-guide.md index ae60a082a3..0f8852bc81 100644 --- a/skills/uipath-rpa/references/execution-maps-guide.md +++ b/skills/uipath-rpa/references/execution-maps-guide.md @@ -17,7 +17,7 @@ One dense file, read once per build. Fixes which tool calls go in which assistan - `templates search` → `init` (Rule 2): runs only when the user names a template or domain pattern; its result (possibly an `AskUserQuestion`) picks `--template-package-id`. - Rule 2a framework/language question when the request carries no signal. - Any `AskUserQuestion` or consent gate. -- UIA capture (Rule 7) — out of map scope entirely; UIA journeys keep their own flow. +- UIA state advances and indication (see [§ Journey: UIA capture + build](#journey-uia-capture--build-xaml)) — capture screens are gated by real application state. ## Journey: Greenfield XAML (no UIA) @@ -60,6 +60,22 @@ Skip the project-discovery subagent — no project exists (SKILL.md § Precondit Brownfield XAML journey with coded reads: T1 `Read` target `.cs` + `.local/docs/.../coded/coded-api.md` for touched services; T2 `Edit`s ∥ install; T3 gate; T4 report. +## Journey: UIA capture + build (XAML) + +Budget shape: **~3 fixed turns + ~3 turns per capture-screen + 2-turn debug cycle.** Capture is serialized ACROSS screens by application state (Complete-then-advance, [uia-configure-target-workflows.md](uia-configure-target-workflows.md)) — never try to batch across an advance. Concrete UIA CLI syntax is package-owned: `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md`. + +| Turn | Emit in ONE assistant message | +|---|---| +| **T0 — Reads + pre-flight** | Parallel `Read`: [ui-automation-guide.md](ui-automation-guide.md) + [uia-configure-target-workflows.md](uia-configure-target-workflows.md) (Rule 7, in full) + package skill docs (`.local/docs/.../skills/uia-configure-target/{SKILL,USAGE}.md`) ∥ prerequisites check ([uia-prerequisites.md](uia-prerequisites.md)) ∥ ONE `Bash`: window baseline via the UIA snapshot CLI ∥ build the element inventory/checklist from manual steps ([ui-automation-guide.md § Capturing from Manual Test Steps](ui-automation-guide.md)) | +| **Per capture-screen** | (a) capture bundle — run the `uia-configure-target` flow for ALL of this screen's checklist elements in one pass (batch `\|` pattern; per-screen batched OR entry points), through OR registration; (b) ONE state advance via the interact CLI — only to reach the next screen, never to test behavior | +| **T-author — after ALL screens captured** | Scaffold/authoring prerequisites (Capture-First Fast Path order) ∥ batch-author every screen's activities in one pass (Rule 18), embed path for OR target attachment | +| **T-gate** | ONE `Bash`: per-file `validate` (relative `--file-path`) `&&` `build` | +| **Debug cycle (consent-gated, § Running UI Automation Workflows)** | ONE `Bash` chain: window baseline `&&` `debug start` `&&` `execution cancel` `&&` re-list windows; next turn: diff, close stray windows via the interact CLI, report | + +- Default is author-once-after-capture — all OR refs are already in conversation. Fall back to per-screen authoring interleave only on long captures (5+ screens) where context pressure is real; the `validate`/`build` gate still runs ONCE at the end either way. +- Indication fallback (user physically clicks) and every interact advance are sequential gates — never batched, never parallel. +- Selector failures at debug time → the `uia-improve-selector` flow (never hand-edit selectors). + ## Failure exits | Symptom | Open | @@ -69,7 +85,7 @@ Brownfield XAML journey with coded reads: T1 `Read` target `.cs` + `.local/docs/ | Coded `CS*` errors | [coded/coding-guidelines.md § Common Issues](coded/coding-guidelines.md) | | CLI error (`timeout`, `EPIPE`, `401`, `not in the project folder`) | [cli-reference.md § CLI Error Recovery](cli-reference.md#cli-error-recovery) | | Card snippet rejected by validate/build | Fall back to Rule 21 triple for that activity; report stale entry via `/uipath-feedback` | -| Anything UIA | Rule 7 flow — leave this map | +| UIA selector fails at debug time | `uia-improve-selector` flow per [ui-automation-guide.md § Runtime Selector Failure Recovery](ui-automation-guide.md) — never hand-edit | ## Cross-session memory @@ -83,6 +99,6 @@ Harness-conditional: engage only when the harness provides persistent memory; ot 2. Error→root-cause→fix triples that cost >1 validate attempt. 3. Cross-version package gotchas. -**Never save:** project-specific facts (paths, asset names, connections — belong in `project-context.md`), anything UIA (selectors/targets are per-app), secrets. +**Never save:** project-specific facts (paths, asset names, connections — belong in `project-context.md`), UIA selectors/targets/OR references (per-app), UIA CLI syntax (package-owned, co-versioned), secrets. Process-level UIA lessons (e.g., a failure mode and its fix direction) MAY be saved. **Expiry:** recalled snippet fails validation → delete/overwrite that entry, fall back to Rule 21 triple. diff --git a/skills/uipath-rpa/references/ui-automation-guide.md b/skills/uipath-rpa/references/ui-automation-guide.md index 9be3ed165b..396e88c2da 100644 --- a/skills/uipath-rpa/references/ui-automation-guide.md +++ b/skills/uipath-rpa/references/ui-automation-guide.md @@ -416,7 +416,7 @@ For XAML-specific activity details: `.local/docs/packages/UiPath.UIAutomation.Ac > "Screen" in this section means the **capture-screen** sense (see § Terminology) — a distinct UI state that requires its own `uia-configure-target` pass because the app has to be advanced between captures. It is NOT the Object Repository screen sense. A workflow that ends up with one Object Repository screen entry can still be multi-screen here — what matters is the number of capture passes separated by `uip rpa uia interact` CLI advances, not the number of `.objects/` screen entries that get created. -For workflows spanning multiple capture screens, add each screen's activities to the workflow as its targets are registered in the Object Repository. All UI activities belong inside the `NApplicationCard` scope. Validate with `validate` after each batch. [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule). +For workflows spanning multiple capture screens, default to **author-once-after-capture**: register every screen's targets first, then batch-author all activities in one pass (Rule 18) — the OR references from every capture are already in conversation. Fall back to per-screen authoring interleave only on long captures (5+ screens) where context pressure is real. Either way, all UI activities belong inside the `NApplicationCard` scope and the per-file `validate` + project `build` gate runs ONCE after authoring completes — not after each screen batch. Turn structure: [execution-maps-guide.md § Journey: UIA capture + build](execution-maps-guide.md#journey-uia-capture--build-xaml). [uia-configure-target-workflows.md](uia-configure-target-workflows.md) MUST be read IN FULL first (see § Multi-Step UI Flows for the capture loop and the Complete-then-advance rule). ### Key Concepts diff --git a/skills/uipath-rpa/references/uia-configure-target-workflows.md b/skills/uipath-rpa/references/uia-configure-target-workflows.md index de0aea1e57..e784a68110 100644 --- a/skills/uipath-rpa/references/uia-configure-target-workflows.md +++ b/skills/uipath-rpa/references/uia-configure-target-workflows.md @@ -175,7 +175,7 @@ When generating a new XAML file or editing one that has not been opened in Studi ### Multi-Screen Workflows -For XAML workflows spanning multiple capture screens, add each screen's activities to the workflow as its OR references become available. Each batch aligns with the Complete-then-advance rule in § Multi-Step UI Flows — everything configured before the next `uip rpa uia interact` advance belongs to one batch. Validate with `validate` after each batch. Attach each target per `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/uia-target-attachment-guide.md`. +For XAML workflows spanning multiple capture screens, default to **author-once-after-capture**: complete every screen's capture + OR registration first (Complete-then-advance per § Multi-Step UI Flows), then batch-author all screens' activities in one pass and gate with `validate` + `build` ONCE (SKILL.md Rule 18). Interleave per-screen authoring only on long captures (5+ screens) under context pressure — the single end gate still applies. Turn structure: [execution-maps-guide.md § Journey: UIA capture + build](execution-maps-guide.md#journey-uia-capture--build-xaml). Attach each target per `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/uia-target-attachment-guide.md`. ## CLI Pitfalls From aa6e2b434de21246a758121a329de83a0731c921 Mon Sep 17 00:00:00 2001 From: Alvin Stanescu Date: Thu, 2 Jul 2026 18:47:46 +0300 Subject: [PATCH 10/10] feat(uipath-rpa): UIA journey carries OR screen reference across capture screens Pairs with UiPath/Activities#38006 (--screen-reference-id passthrough in the package skill); category-pointer only, syntax stays package-owned. Co-Authored-By: Claude Fable 5 --- skills/uipath-rpa/references/execution-maps-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/uipath-rpa/references/execution-maps-guide.md b/skills/uipath-rpa/references/execution-maps-guide.md index 0f8852bc81..69174b5abc 100644 --- a/skills/uipath-rpa/references/execution-maps-guide.md +++ b/skills/uipath-rpa/references/execution-maps-guide.md @@ -73,6 +73,7 @@ Budget shape: **~3 fixed turns + ~3 turns per capture-screen + 2-turn debug cycl | **Debug cycle (consent-gated, § Running UI Automation Workflows)** | ONE `Bash` chain: window baseline `&&` `debug start` `&&` `execution cancel` `&&` re-list windows; next turn: diff, close stray windows via the interact CLI, report | - Default is author-once-after-capture — all OR refs are already in conversation. Fall back to per-screen authoring interleave only on long captures (5+ screens) where context pressure is real; the `validate`/`build` gate still runs ONCE at the end either way. +- Screens after the first (same window): carry the OR screen reference from the previous capture into the next `uia-configure-target` invocation — it skips the OR screen lookup. Invocation shape and argument: the package skill's `USAGE.md` § Multi-screen capture sessions. - Indication fallback (user physically clicks) and every interact advance are sequential gates — never batched, never parallel. - Selector failures at debug time → the `uia-improve-selector` flow (never hand-edit selectors).