@uipath/skills 1.195.0

package/skills/uipath-maestro-bpmn/references/author/CAPABILITY.md

@@ -0,0 +1,141 @@
+# Author - Create and edit BPMN Process Orchestration projects
+
+Capability index for local BPMN project authoring. Author owns source edits, local inspection, validation, and CLI enrichment planning. It does not upload, publish, debug, or run cloud instances.
+
+> Inherits universal rules from [SKILL.md](../../SKILL.md). Read [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) before changing XML boundaries.
+
+## When to use this capability
+
+- Create a Maestro BPMN project scaffold.
+- Edit `.bpmn` XML for process structure, diagrams, variables, bindings, entry points, scripts, timers, messages, gateways, subprocesses, boundary errors, and documented non-Integration-Service UiPath extensions.
+- Inspect an existing BPMN project and identify source versus generated files.
+- Run the two-pass authoring workflow: standard BPMN skeleton first, operator shape confirmation second, UiPath extension fill last.
+- Plan Integration Service nodes/triggers that must be CLI-enriched.
+- Run local validation before handing off to Operate.
+
+## Context budget
+
+For greenfield authoring, read only the files needed for the current step:
+
+1. This capability file.
+2. [shared/project-layout.md](../shared/project-layout.md).
+3. [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md).
+4. [references/planning-arch.md](references/planning-arch.md) for pass 1.
+5. [references/planning-impl.md](references/planning-impl.md) and only the specific plugin or task recipe needed for pass 2.
+6. [references/validation.md](references/validation.md) before reporting done.
+
+Do not bulk-read the full skill tree or validation fixtures during normal
+authoring. Validation fixtures are coverage examples, not greenfield authoring
+templates. Open fixtures only after a validation failure or a directly linked
+guide requires a concrete example, and then read the smallest relevant fixture.
+
+## Critical rules
+
+1. **Use the two-pass workflow for non-trivial authoring** - first generate or edit a pure BPMN skeleton with readable IDs and diagram geometry, then ask the operator to confirm the process shape, then add UiPath variables, bindings, mappings, entry points, and documented non-Integration-Service extensions.
+2. **Keep pass 1 standard BPMN-first** - pass 1 may include placeholders and annotations for resource intent, but it must not invent `uipath:activity`, `uipath:event`, connector bindings, generated schemas, or package metadata.
+3. **Read the BPMN XML contract before editing** - the Maestro BPMN contract defines which XML the model may author and which pieces require CLI generation or enrichment.
+4. **Default to reviewable file edits for BPMN source** - edit `.bpmn` directly for model-owned XML so diffs stay inspectable.
+5. **Choose BPMN element class before resource recipe** - RPA, agents, and API workflows are service tasks; queue create is a send task; business rules are business rule tasks; HITL is a user task. Task recipes are pass-2 implementation references and assume the skeleton has already been chosen. See [supported-elements.md](references/supported-elements.md).
+6. **Do not hand-author Integration Service details** - use [plugins/integration-service/](references/plugins/integration-service/) for the planning and implementation boundary.
+7. **Keep generated package files derived** - if `bindings_v2.json`, `entry-points.json`, `operate.json`, or `package-descriptor.json` is stale, prefer regeneration or validation over manual patching.
+8. **Every Studio Web-visible element needs diagram geometry** - ensure diagrams, planes, shapes, bounds, edges, and waypoints exist for rendered nodes and flows.
+9. **Validate once the full local edit is coherent** - intermediate BPMN edits may be invalid while IDs, flows, and diagrams are being reconciled.
+10. **Preserve unknown imported extensions** - do not delete extension elements the skill cannot interpret unless the user explicitly asks for normalization.
+11. **Use synthetic examples only** - never copy private exported BPMN into local fixtures, docs, or comments.
+
+## Two-pass workflow
+
+Use this workflow for greenfield projects and for brownfield edits that change topology, entry points, service calls, subprocess boundaries, or variable contracts.
+
+1. **Plan the process shape** - identify starts, human/system steps, gateways, subprocesses, timers/messages, error paths, end states, variables, resources, and Integration Service enrichment needs. See [planning-arch.md](references/planning-arch.md).
+2. **Pass 1: author the BPMN skeleton** - create or edit standard BPMN elements, sequence flows, event definitions, diagram planes, shapes, edges, and placeholder labels. Keep this pass mostly free of UiPath extension XML except preserving existing extensions in brownfield files.
+3. **Operator shape confirmation** - summarize the skeleton in process terms and explicitly confirm starts, branches, joins, subprocess boundaries, error paths, and external-system placeholders before filling execution metadata.
+4. **Pass 2: fill model-owned UiPath XML** - add root variables, entry point IDs, mappings, bindings, scripts, retry/error metadata, and documented non-Integration-Service `uipath:activity` or `uipath:event` shells. See [planning-impl.md](references/planning-impl.md).
+5. **CLI enrichment handoff** - run or request registry-backed enrichment for Integration Service activities/triggers and generated package metadata. If tooling is unavailable, leave draft intent documented and keep the project in Author state.
+6. **Validate and summarize** - run local validation after the source is coherent, then report validation status, generated-file status, and unresolved enrichment blockers.
+
+## Workflow
+
+| Journey | Read |
+| --- | --- |
+| Create a new BPMN project | [references/greenfield.md](references/greenfield.md) |
+| Edit an existing BPMN project | [references/brownfield.md](references/brownfield.md) |
+| Plan the process topology and enrichment boundary | [references/planning-arch.md](references/planning-arch.md) |
+| Fill variables, bindings, expressions, and UiPath extensions | [references/planning-impl.md](references/planning-impl.md) |
+| Choose an editing operation | [references/editing-operations.md](references/editing-operations.md) |
+| Choose what the model may write | [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) |
+| Choose supported BPMN elements and extension wrappers | [references/supported-elements.md](references/supported-elements.md) |
+| Copy a minimal XML shell for a wrapper | [shared/wrapper-shells.md](../shared/wrapper-shells.md) |
+| Add resource-backed task recipes | [references/task-recipes/](references/task-recipes/) |
+| Work with Integration Service nodes/triggers | [references/plugins/integration-service/](references/plugins/integration-service/) |
+
+## Common tasks
+
+| I need to... | Read these |
+| --- | --- |
+| Understand project files | [shared/project-layout.md](../shared/project-layout.md) |
+| Create a confirmed BPMN skeleton | [references/planning-arch.md](references/planning-arch.md) + [references/greenfield.md](references/greenfield.md) |
+| Add or revise BPMN structure | [references/brownfield.md](references/brownfield.md) + [references/editing-operations.md](references/editing-operations.md) + [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) |
+| Add variables, mappings, bindings, or expressions | [references/planning-impl.md](references/planning-impl.md) + [shared/variables-bindings-expressions.md](../shared/variables-bindings-expressions.md) |
+| Add lint-compatible runtime expressions | [shared/expression-authoring.md](../shared/expression-authoring.md) |
+| Add retry, boundary errors, or error mappings | [shared/error-handling.md](../shared/error-handling.md) |
+| Select the right BPMN wrapper for RPA, agent, API workflow, queue, HITL, business rule, or call activity work | [references/supported-elements.md](references/supported-elements.md) + [references/task-recipes/](references/task-recipes/) |
+| Add an Integration Service activity or trigger | [references/plugins/integration-service/](references/plugins/integration-service/) |
+| Add a specific BPMN or UiPath extension element | [Plugin references](#plugin-references) |
+| Prepare for upload or run | [references/validation.md](references/validation.md) then [operate/CAPABILITY.md](../operate/CAPABILITY.md) |
+| Keep authored content public-safe | [shared/public-safety.md](../shared/public-safety.md) |
+
+## Anti-patterns
+
+- **Never omit BPMN DI for a process intended for Studio Web.**
+- **Never skip operator shape confirmation for a substantial topology change.**
+- **Never mix skeleton design and executable connector enrichment in one opaque rewrite.**
+- **Never patch generated JSON to hide a BPMN source problem.**
+- **Never paste a real connection ID, folder key, tenant URL, or exported XML snippet into the project.**
+- **Never downgrade an Integration Service node to a generic task just because enrichment is unavailable** - keep the node as a draft intent and report the blocker.
+- **Never assume imported extension XML is disposable** - preserve first, normalize only on explicit request.
+
+## References
+
+### Author-scoped
+
+- [greenfield.md](references/greenfield.md) - create-new-project journey
+- [brownfield.md](references/brownfield.md) - edit-existing-project journey
+- [planning-arch.md](references/planning-arch.md) - pass 1 BPMN skeleton planning
+- [planning-impl.md](references/planning-impl.md) - pass 2 UiPath extension fill
+- [editing-operations.md](references/editing-operations.md) - safe edit operations for BPMN XML
+- [supported-elements.md](references/supported-elements.md) - supported BPMN elements and UiPath extension wrappers
+- [task-recipes/](references/task-recipes/) - BPMN-first recipes for resource-backed tasks
+- [validation.md](references/validation.md) - local validation checklist
+- [plugins/integration-service/](references/plugins/integration-service/) - Integration Service planning and CLI enrichment boundary
+
+### Plugin references
+
+Each plugin reference has a `planning.md` for pass 1 shape/resource decisions and an `impl.md` for pass 2 XML ownership and validation boundaries.
+
+- [plugins/start-end-events/](references/plugins/start-end-events/) - start events, end events, intermediate events, and boundary events
+- [plugins/gateways/](references/plugins/gateways/) - exclusive, inclusive, parallel, and event-based gateways
+- [plugins/sequence-flows/](references/plugins/sequence-flows/) - control-flow edges, conditions, defaults, and diagram waypoints
+- [plugins/service-tasks/](references/plugins/service-tasks/) - base service task boundary; use [task-recipes/](references/task-recipes/) for concrete resource-backed tasks
+- [plugins/connectors/](references/plugins/connectors/) - connector-backed activities, triggers, waits, and dynamic schemas
+- [plugins/waits-triggers/](references/plugins/waits-triggers/) - timers, waits, triggers, receives, and timeout behavior
+- [plugins/script/](references/plugins/script/) - script tasks, script metadata, inputs, outputs, and error paths
+- [plugins/hitl/](references/plugins/hitl/) - user task representation for Action Center work
+- [plugins/queues/](references/plugins/queues/) - send task or service task representation for queue work
+- [plugins/call-activity-subprocess/](references/plugins/call-activity-subprocess/) - call activities, subprocesses, event subprocesses, and scoped mappings
+- [plugins/multi-instance/](references/plugins/multi-instance/) - sequential or parallel collection processing
+- [plugins/agents/](references/plugins/agents/) - service task recipes for agent job and A2A execution shells
+- [plugins/rpa-jobs/](references/plugins/rpa-jobs/) - service task recipe for Orchestrator RPA process execution
+- [plugins/api-workflows/](references/plugins/api-workflows/) - service task recipe for API workflow invocation
+- [plugins/signals/](references/plugins/signals/) - preserve-only signal guidance for imported files
+- [plugins/business-rules/](references/plugins/business-rules/) - business rule task invocation and result routing
+
+### Cross-capability
+
+- [shared/bpmn-xml-contract.md](../shared/bpmn-xml-contract.md) - model-owned versus CLI-owned XML
+- [shared/project-layout.md](../shared/project-layout.md) - source and generated files
+- [shared/variables-bindings-expressions.md](../shared/variables-bindings-expressions.md) - variables, bindings, mappings, expressions
+- [shared/expression-authoring.md](../shared/expression-authoring.md) - lint-compatible runtime expressions
+- [shared/error-handling.md](../shared/error-handling.md) - Maestro retry, boundary error, event subprocess, and error mapping behavior
+- [shared/cli-conventions.md](../shared/cli-conventions.md) - CLI and side-effect conventions
+- [shared/public-safety.md](../shared/public-safety.md) - sanitization rules

package/skills/uipath-maestro-bpmn/references/author/references/brownfield.md

@@ -0,0 +1,48 @@
+# Brownfield Authoring
+
+Use this journey when inspecting or editing an existing Maestro BPMN Process Orchestration project.
+
+## Steps
+
+1. Inventory local files: BPMN source, project metadata, generated JSON, and any package output.
+2. Identify the primary `.bpmn` source file and preserve imported extension XML.
+3. Parse the BPMN mentally before editing: definitions, root process, diagrams, IDs, variables, bindings, entry points, and service extensions.
+4. Classify requested edits as model-owned XML, CLI-owned enrichment, generated package metadata, or cloud lifecycle.
+5. If topology changes, run **pass 1** from [planning-arch.md](planning-arch.md): edit the standard BPMN skeleton first, including IDs, flows, events, gateways, subprocess scopes, and diagram geometry.
+6. Summarize the changed shape and ask for operator confirmation when the edit changes the process path, entry points, subprocess boundaries, or error handling.
+7. Run **pass 2** from [planning-impl.md](planning-impl.md): update model-owned variables, bindings, mappings, entry point IDs, scripts, and non-Integration-Service extension XML.
+8. For Integration Service changes, follow [plugins/integration-service/impl.md](plugins/integration-service/impl.md) and use CLI enrichment where available.
+9. Reconcile IDs, sequence flows, gateway defaults, boundary attachments, scoped variables, binding references, and diagram geometry.
+10. Run local validation from [validation.md](validation.md).
+11. Summarize whether generated JSON needs regeneration before Operate.
+
+## Preservation rules
+
+- Preserve unknown `uipath:*` extension elements.
+- Preserve existing `uipath:migrationVersion` values.
+- Preserve tags unless the user asks to remove them.
+- Preserve generated JSON for comparison, but do not treat it as authoritative over BPMN.
+- Preserve Integration Service payloads as imported unless CLI enrichment is explicitly updating them.
+- Preserve stable element IDs when possible; ID churn makes generated JSON and runtime diagnostics harder to compare.
+
+## Editing operation guide
+
+Use [editing-operations.md](editing-operations.md) for common source mutations:
+
+- Add, delete, or reconnect nodes.
+- Insert gateways.
+- Move logic into a subprocess.
+- Add entry points.
+- Add variables and mappings.
+- Add Integration Service placeholders.
+
+## Red flags
+
+- BPMN imports without any diagram.
+- A diagram plane references a missing process, collaboration, or subprocess.
+- Rendered elements lack shapes or waypoints.
+- Entry point variables reference the wrong start event.
+- Context values reference missing bindings.
+- Integration Service elements contain hand-authored connection details.
+- Generated JSON contains private tenant data in a file intended for commit.
+- A topology edit rewrites UiPath extension XML that was unrelated to the request.

package/skills/uipath-maestro-bpmn/references/author/references/editing-operations.md

@@ -0,0 +1,75 @@
+# Editing Operations
+
+Use this reference to choose how to change existing BPMN projects while preserving source clarity and imported extension XML.
+
+## Tool selection ladder
+
+1. **Reviewable XML edit** - default for `.bpmn` source changes: elements, flows, diagrams, variables, mappings, scripts, and documented non-Integration-Service extensions.
+2. **CLI enrichment or generation** - use for Integration Service activities/triggers, generated schemas, bindings resources, entry points, packaging metadata, and project scaffolding when commands are available.
+3. **Advisory placeholder** - use when the requested executable metadata is CLI-owned but enrichment tooling or user resource selection is unavailable.
+4. **Bulk rewrite** - use only when most of the BPMN source is being replaced, and preserve or explicitly account for existing extension payloads first.
+
+Do not patch generated JSON files as the primary way to fix source behavior.
+
+## Add a task or event
+
+1. Add the BPMN element with a stable ID and public-safe name.
+2. Add incoming and outgoing sequence flow references on the element.
+3. Add sequence flow elements in the owning process or subprocess scope.
+4. Add or update BPMN DI shape and edge waypoints.
+5. Add pass 2 extension XML only after the shape is confirmed.
+
+## Delete a node
+
+1. Identify incoming and outgoing flows, attached boundary events, data associations, mappings, and diagram shapes.
+2. Decide whether neighboring nodes should reconnect or whether the branch should be removed.
+3. Remove orphaned sequence flows and BPMN DI edges.
+4. Remove or preserve extension data intentionally; do not delete unknown `uipath:*` payloads unless normalizing explicitly.
+5. Recheck entry point variables, output mappings, and binding references.
+
+## Insert a gateway
+
+1. Split the existing sequence flow into incoming and outgoing flows.
+2. Add gateway conditions to outgoing flows when it is a decision split.
+3. Set a default flow when a fallthrough route exists.
+4. Add a matching join only when branches actually need synchronization.
+5. Add gateway shape and all edge waypoints.
+
+## Move logic into a subprocess
+
+1. Move only elements that share a valid scope.
+2. Recreate incoming/outgoing flow boundaries with legal subprocess connections.
+3. Add a subprocess shape and, when nested content must render in Studio Web, a second diagram plane for the subprocess.
+4. Move variables into subprocess scope only when every mapping and expression remains valid.
+5. Preserve existing extension payloads and migration metadata.
+
+## Add an entry point
+
+1. Use a root-level start event.
+2. Add `uipath:entryPointId` with a generated stable unique value.
+3. Add input variables with `elementId` matching the start event.
+4. Ensure outputs are declared as root output variables and mapped by reachable end events.
+5. Validate generated `entry-points.json` when package files exist.
+
+## Add a variable or mapping
+
+1. Choose root or subprocess scope deliberately.
+2. Add the variable before adding mappings or expressions that reference it.
+3. Use CDATA for JSON schema bodies.
+4. Add `uipath:mapping` or service outputs that reference declared variables.
+5. Validate all output targets and entry point schema extraction.
+
+## Add an Integration Service activity or trigger
+
+1. Add the standard BPMN wrapper and diagram geometry in pass 1.
+2. Record connector, operation/event, object, filters, required inputs, connection selection, and outputs.
+3. Use CLI enrichment for `uipath:activity` or `uipath:event` payloads, bindings, and schemas.
+4. Treat missing enrichment as a blocker for upload/debug/publish/run.
+
+## Brownfield preservation checklist
+
+- Preserve unknown `uipath:*` extension elements.
+- Preserve `uipath:migrationVersion` and tags.
+- Preserve generated JSON for comparison unless regeneration is requested.
+- Preserve private values already present locally, but never copy them into docs, fixtures, or commit messages.
+- Report suspected private values in files intended for commit.

package/skills/uipath-maestro-bpmn/references/author/references/greenfield.md

@@ -0,0 +1,41 @@
+# Greenfield Authoring
+
+Use this journey when creating a new Maestro BPMN Process Orchestration project.
+
+## Steps
+
+1. Confirm the requested process goal, trigger, major steps, external systems, and resources that already exist.
+2. Create the canonical project scaffold using the available Maestro BPMN scaffolding command or the repository's current Maestro project template.
+3. Create or edit the primary `.bpmn` file as the source of record.
+4. **Pass 1: build the standard BPMN skeleton** from [planning-arch.md](planning-arch.md): root process, starts, tasks, gateways, subprocesses, events, error paths, sequence flows, and BPMN DI.
+5. Summarize the process shape and ask the operator to confirm it before filling executable UiPath metadata when the process is non-trivial.
+6. **Pass 2: fill model-owned UiPath XML** from [planning-impl.md](planning-impl.md): root variables, entry point IDs, mappings, bindings, scripts, retry/error metadata, and documented non-Integration-Service service shells.
+7. For Integration Service activities/triggers, follow [plugins/integration-service/planning.md](plugins/integration-service/planning.md) and leave CLI-owned details to enrichment.
+8. Run local validation from [validation.md](validation.md).
+9. Hand off to Operate only after validation is clean or the remaining issues are explicit user-approved warnings.
+
+## Design defaults
+
+- Prefer a simple root process before adding pools or collaborations.
+- Prefer readable deterministic element IDs.
+- Keep diagram layout simple and inspectable.
+- Use placeholder-safe resource names until discovery/enrichment resolves real resources.
+- Keep pass 1 skeleton diffs separate from pass 2 execution metadata when practical.
+- Keep all examples and fixtures synthetic.
+
+## Shape confirmation prompt
+
+For non-trivial processes, summarize:
+
+- Trigger and entry point.
+- Ordered happy path.
+- Branches, joins, and default paths.
+- Error, timeout, and terminate behavior.
+- Subprocess boundaries.
+- External-system placeholders and enrichment blockers.
+
+Proceed to pass 2 only after the operator confirms the shape or the edit is small enough to summarize without a formal stop.
+
+## Done state
+
+Authoring is done when BPMN source is coherent, generated or CLI-managed files are up to date or intentionally absent, validation has been run, and any Integration Service enrichment blockers are documented.

package/skills/uipath-maestro-bpmn/references/author/references/planning-arch.md

@@ -0,0 +1,82 @@
+# Planning Architecture
+
+Use this reference for pass 1 of BPMN authoring: create a standard BPMN skeleton that the operator can understand and confirm before execution-specific UiPath XML is filled.
+
+## Pass 1 goal
+
+Pass 1 produces a reviewable process shape:
+
+- Root process or collaboration choice.
+- Start events and intended entry points.
+- Tasks, subprocesses, gateways, events, error boundaries, and end states.
+- Sequence flows, conditions in plain process terms, and default routes.
+- Diagram plane, shapes, bounds, edges, and waypoints.
+- Placeholder labels or annotations for external resources that need pass 2 or CLI enrichment.
+
+Pass 1 does not need runnable UiPath service metadata. It should be valid enough to inspect as BPMN, but it may intentionally leave executable service details unresolved.
+
+## Intake checklist
+
+Before drafting the skeleton, identify:
+
+- Process trigger: manual start, schedule, message, Integration Service trigger, timer, or another process.
+- Happy path steps and the owner of each step: human, BPMN script, Orchestrator process, agent, API workflow, queue, business rule, message, or connector.
+- Branching conditions and whether each gateway needs a default route.
+- Parallel work and join behavior.
+- Subprocess boundaries and whether nested content must render in Studio Web.
+- Retry and error-handling intent: boundary error, event subprocess, terminate end, or normal compensation path.
+- Variables crossing entry points, subprocesses, service tasks, and end events.
+- Resources that already exist versus placeholders that need discovery or CLI enrichment.
+
+## Skeleton authoring rules
+
+- Use one executable root `bpmn:process` by default.
+- Use collaboration and pools only when the user explicitly requests cross-participant modeling.
+- Prefer stable, readable IDs such as `Start_RequestReceived`, `Task_CheckEligibility`, `Gateway_Approved`, and `Flow_Check_To_Approve`.
+- Keep labels public-safe and user-readable.
+- Create BPMN DI while creating elements; do not leave layout as a later afterthought.
+- Put conditions on outgoing sequence flows from exclusive or inclusive gateway splits.
+- Keep pass 1 conditions in business-readable terms. Do not use
+  Maestro runtime expressions such as `=vars.<variableId>` until pass 2 has
+  declared the variables and mappings those expressions reference.
+- Keep script tasks structural in pass 1. A pass 1 `bpmn:scriptTask` may have a
+  readable name or documentation, but executable script bodies and
+  UiPath script mappings belong in pass 2.
+- Set a `default` sequence flow when the business process has a fallthrough route.
+- Model errors with boundary events or event subprocesses instead of unlabeled failure branches when the runtime should handle failures structurally.
+- Keep sequence flows inside their owning process or subprocess scope.
+
+## Operator confirmation
+
+After pass 1, summarize the shape in business terms and wait for confirmation when the change is non-trivial.
+
+Confirmation should cover:
+
+- Entry points and trigger type.
+- Step order and major branches.
+- Join semantics for parallel branches.
+- Subprocess boundaries.
+- Error and timeout behavior.
+- Which placeholders represent Integration Service, Orchestrator, HITL, agent, queue, API workflow, or other resources.
+- Any intentionally unresolved resource selection.
+
+For small edits, confirmation can be a concise statement such as: "I changed only the timeout branch from Task_A to Event_Timeout and kept all existing variables and service metadata unchanged."
+
+## Integration Service placeholders
+
+When a connector activity or trigger is needed in pass 1:
+
+- Add the surrounding BPMN element with a stable ID and public-safe label.
+- Record connector intent: connector, operation/event, object, filters, required parameters, and desired outputs.
+- Do not author `Intsvc.*` context, connection binding IDs, connector metadata, dynamic schemas, or generated outputs by hand.
+- Mark enrichment as required before upload, debug, publish, or deploy.
+
+For plain connectionless HTTP where the workflow owns the URL, method, payload,
+and parsing, record the node as a plain HTTP candidate in pass 1 instead of
+treating it as connector enrichment. After the operator confirms the skeleton,
+use [task-recipes/http-request.md](task-recipes/http-request.md) only for the
+pass-2 executable wrapper.
+
+## Done state
+
+Pass 1 is done when the operator can review the BPMN diagram and answer: "Is this the process shape we want?" without needing to inspect UiPath extension XML.

package/skills/uipath-maestro-bpmn/references/author/references/planning-impl.md

@@ -0,0 +1,104 @@
+# Planning Implementation
+
+Use this reference for pass 2 of BPMN authoring: fill the model-owned UiPath extension XML after the BPMN skeleton has been confirmed.
+
+## Pass 2 goal
+
+Pass 2 makes the confirmed skeleton locally coherent for validation and packaging:
+
+- Root variables and scoped subprocess variables.
+- Entry point IDs on runnable root start events.
+- Variable mappings on tasks, events, scripts, subprocesses, and ends.
+- Lint-compatible expressions using [expression-authoring.md](../../shared/expression-authoring.md).
+- Resource bindings for documented non-Integration-Service service shells and
+  the plain connectionless HTTP recipe.
+- Script task metadata and input/output mapping.
+- Retry, error mapping, multi-instance metadata, UiPath transaction-root marker,
+  and tags when specified.
+- Draft Integration Service intent handed to CLI enrichment.
+
+## Fill order
+
+1. **Entry points** - add `uipath:entryPointId` to root start events that should be runnable.
+2. **Variables** - add root `uipath:variables` for entry point inputs, process globals, outputs, and schemas; add subprocess variables only when scope requires them.
+3. **Mappings** - add `uipath:mapping` where values move between variables, task inputs, task outputs, and end outputs.
+4. **Bindings** - add root `uipath:bindings` only for documented non-Integration-Service resources or placeholder-safe binding shapes.
+5. **Task shells** - add documented non-Integration-Service `uipath:activity` or `uipath:event` metadata, or the plain connectionless HTTP recipe, when the task wrapper and service type contract are known. Use [supported-elements.md](supported-elements.md) and [task-recipes/](task-recipes/) before writing XML.
+6. **Scripts** - add BPMN script CDATA, `uipath:scriptVersion`, merged `args` input, schema, and outputs.
+7. **Runtime behavior metadata** - add retry, error mapping, documented
+   multi-instance characteristics, UiPath transaction-root marker, or tags only
+   when user intent is explicit. Use [error-handling.md](../../shared/error-handling.md)
+   for retry, boundary error, event subprocess, and error mapping shapes. Do not
+   generate `bpmn:transaction`; it is preserve-only.
+8. **CLI-owned enrichment** - hand Integration Service activities/triggers and generated package metadata to the CLI.
+
+## Variables
+
+Root variables define the public entry point contract and process-wide data. Use stable IDs and preserve existing IDs during brownfield edits unless renaming is required.
+
+- `uipath:input` is read-only entry input.
+- `uipath:inputOutput` can be updated during execution.
+- `uipath:output` is emitted by entry point outputs.
+- `elementId` scopes entry inputs to the root start event that owns the entry point.
+- JSON schema variables store schema content in CDATA.
+- Do not move a variable between root and subprocess scope without checking every mapping and expression.
+
+## Bindings
+
+Root bindings describe resources that packaging turns into `bindings_v2.json`.
+
+- Use expressions in service context values: `=bindings.<binding id>`.
+- Keep `resourceKey`, `resourceSubType`, and `propertyAttribute` placeholder-safe unless a public-safe value is provided.
+- Do not paste connection IDs, folder keys, URLs, queue IDs, release keys, or tenant-specific names.
+- Let the CLI generate or enrich binding resources for Integration Service and dynamic schemas.
+
+## Expressions
+
+- Use a leading `=` where Maestro expects an expression.
+- Treat strings without `=` as literals.
+- Avoid assignment operators in condition, skip, and mapping expressions where fields require read-only expression evaluation.
+- Keep gateway condition expressions on sequence flows, not on the gateway itself.
+- Keep script source in BPMN `script` CDATA with `scriptFormat="JavaScript"`.
+- Read [expression-authoring.md](../../shared/expression-authoring.md) before
+  writing `vars`, `result`, `bindings`, `iterator`, or `vars.error` references.
+
+## Non-Integration-Service task shells
+
+The model may fill documented non-Integration-Service shells only when the required fields are known and public-safe. Examples include variable mappings, script tasks, Orchestrator process/agent/API workflow starts, business rules, queue item creation, HITL, message events, and supported agent execution shells.
+
+Wrapper choices are not optional:
+
+- RPA, agent, API workflow, A2A, and create-and-wait queue work use `bpmn:serviceTask`.
+- Queue create uses `bpmn:sendTask`.
+- Business rules use `bpmn:businessRuleTask`.
+- HITL uses `bpmn:userTask`.
+- Agentic and case-management process calls use `bpmn:callActivity`.
+- Script work uses `bpmn:scriptTask`.
+
+For every shell:
+
+- Include the correct `uipath:type` service type and version only when documented.
+- Add required `uipath:context` fields inside `uipath:activity` or `uipath:event`.
+- Add task payload inputs and output mappings in a sibling
+  `uipath:mapping version="v1"` element.
+- Use CDATA for JSON payload `uipath:input` bodies and target declared
+  variables with `uipath:output var="..."`.
+- Validate that each binding or variable reference resolves.
+
+## Integration Service handoff
+
+For connector-backed or dynamically schematized `Intsvc.*` activities and triggers, pass 2 should stop at the enrichment boundary unless registry-backed CLI output is available. Confirmed plain connectionless HTTP is the documented pass-2 exception and must follow [task-recipes/http-request.md](task-recipes/http-request.md).
+
+The CLI must own:
+
+- Connector key, operation/event, object, and version metadata.
+- Selected connection binding and generated resource metadata.
+- Trigger property bindings.
+- Dynamic input/output schemas and generated output metadata.
+- `bindings_v2.json` entries.
+
+If the CLI cannot enrich yet, leave a clear blocker in the summary and do not treat the project as ready for Operate.
+
+## Done state
+
+Pass 2 is done when model-owned XML is complete, Integration Service enrichment is either complete or explicitly blocked, generated package files are current or intentionally absent, and validation has been run.

package/skills/uipath-maestro-bpmn/references/author/references/plugins/agents/impl.md

@@ -0,0 +1,34 @@
+# Agent Implementation
+
+This document defines the implementation boundary for agent task recipes. Agents are implemented as `bpmn:serviceTask`; see [task-recipes/agent-job.md](../../task-recipes/agent-job.md) for the per-deployment-style shell decision table.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:serviceTask` wrapper for agent invocation.
+- Draft `Orchestrator.StartAgentJob` activity shell only for folder-deployed
+  dependencies confirmed as `processType: "Agent"`. Use resolved process
+  identity context from the current shell guidance, generated bindings, and
+  current input/output schema metadata.
+- `A2A.AgentExecution` activity shell for external A2A agents addressed by URL/skillId/authToken.
+- Input CDATA for public-safe invocation payloads.
+- Output mappings for job ID, status, result, and structured fields.
+- Timeout/error boundary events and validation gateways.
+
+## CLI or operator-owned implementation
+
+The CLI or operator must resolve:
+
+- Real agent resource identity, version, folder, and binding metadata.
+- Dynamic schemas for agent inputs and outputs.
+- Deployment, creation, or modification of the agent itself.
+
+## Validation expectations
+
+- Agent resource binding resolves before upload/run. For `StartAgentJob`, local
+  validation only proves source and package structure; an authorized run in the
+  target environment is required before claiming runtime behavior.
+- Input variables and output variables exist.
+- Timeout and invalid-output paths are modeled when needed.
+- High-impact outputs have review or validation gates when required by user intent.

package/skills/uipath-maestro-bpmn/references/author/references/plugins/agents/planning.md

@@ -0,0 +1,38 @@
+# Agent Planning
+
+Use this reference when planning agent execution from BPMN. Agents are resource recipes for `bpmn:serviceTask`, not peer BPMN element types. See [task-recipes/agent-job.md](../../task-recipes/agent-job.md).
+
+## When to use
+
+- Starting a UiPath agent job.
+- Calling an A2A or external agent execution shell.
+- Routing based on agent status, answer, or structured output.
+- Combining agent work with HITL validation, RPA jobs, or business rules.
+
+## Planning steps
+
+1. Identify agent type, invocation style, input contract, output contract, and timeout behavior.
+2. Decide whether the agent resource already exists or must be created by a sibling workflow outside this skill.
+3. Plan variables for prompt/input, structured output, status, and errors.
+4. Add validation or HITL review if agent output affects high-impact decisions.
+5. Use placeholder-safe bindings for agent resources.
+6. Plan fallback paths for timeout, no answer, or invalid output.
+
+## Model may draft
+
+- `bpmn:serviceTask` wrapper with the wrapper shell that matches the process
+  type and invocation style (`Orchestrator.StartAgentJob` draft shell for
+  folder-deployed dependencies confirmed as `processType: "Agent"`;
+  `A2A.AgentExecution` for external A2A; `Intsvc.*AgentExecution` for
+  Integration Service external agents). See
+  [../../task-recipes/agent-job.md](../../task-recipes/agent-job.md) for the
+  decision table.
+- For `Orchestrator.StartAgentJob`, resolved process identity context and
+  generated process bindings from the current shell guidance. Do not treat
+  local validation as proof of executable agent invocation.
+- Input/output mappings, boundary timeout/error paths, and gateways.
+- Public-safe resource placeholders.
+
+## Stop conditions
+
+Stop before Operate when agent identity, version, input schema, output schema, or resource binding is unresolved.

package/skills/uipath-maestro-bpmn/references/author/references/plugins/api-workflows/impl.md

@@ -0,0 +1,37 @@
+# API Workflow Implementation
+
+This document defines the implementation boundary for API workflow task recipes. API workflows are implemented as `bpmn:serviceTask`; see [task-recipes/api-workflow.md](../../task-recipes/api-workflow.md).
+
+Use the canonical shell from
+[shared/wrapper-shells.md](../../../../shared/wrapper-shells.md): a
+`bpmn:serviceTask` containing `uipath:activity version="v1"` and nested
+`uipath:type value="Orchestrator.ExecuteApiWorkflowAsync" version="v1"`,
+with request and result payloads as direct `uipath:activity` children.
+Do not author new API workflow XML with legacy
+`<uipath:activity type="Orchestrator.ExecuteApiWorkflowAsync">` shorthand.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:serviceTask` wrapper for API workflow execution.
+- Documented `Orchestrator.ExecuteApiWorkflowAsync` `uipath:activity` shell.
+- Request input CDATA in `uipath:activity` using `vars.<variableId>` references.
+- `uipath:activity` outputs for invocation result and errors.
+- Retry and boundary error metadata when specified.
+
+## CLI or operator-owned implementation
+
+The CLI or operator must resolve:
+
+- Real API workflow resource identity and folder binding.
+- Dynamic request and response schemas.
+- Generated binding resources and package metadata.
+
+## Validation expectations
+
+- Workflow binding resolves before upload/run.
+- Request body matches the resolved schema.
+- Output mappings target declared writable variable ids.
+- Fire-and-forget versus wait behavior is explicit.
+- No private endpoint URLs, resource IDs, or exported payloads are committed.

package/skills/uipath-maestro-bpmn/references/author/references/plugins/api-workflows/planning.md

@@ -0,0 +1,28 @@
+# API Workflow Planning
+
+Use this reference when planning API workflow execution from BPMN. API workflows are resource recipes for `bpmn:serviceTask`, not peer BPMN element types. See [task-recipes/api-workflow.md](../../task-recipes/api-workflow.md).
+
+## When to use
+
+- Calling an Orchestrator API workflow asynchronously.
+- Passing structured request data to an API workflow.
+- Routing based on workflow status or structured response.
+- Combining API workflows with connector, agent, RPA, or HITL steps.
+
+## Planning steps
+
+1. Identify API workflow resource, input schema, output schema, timeout, and error behavior.
+2. Decide whether execution is fire-and-forget or waits for completion.
+3. Plan request variables, response variables, job/status variables, and mapping.
+4. Add retries or boundary errors for transient failures.
+5. Use placeholders until the API workflow binding and schemas are resolved.
+
+## Model may draft
+
+- `bpmn:serviceTask` wrapper with documented `Orchestrator.ExecuteApiWorkflowAsync` shell.
+- Input/output mappings and public-safe request examples.
+- Boundary error paths and gateways.
+
+## Stop conditions
+
+Stop before Operate when workflow identity, schema, binding, or wait semantics are unresolved.