[codex] Add Maestro BPMN element plugin docs

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

@@ -58,6 +58,7 @@ Use this workflow for greenfield projects and for brownfield edits that change t
 | 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 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) |
 
@@ -83,6 +84,27 @@ Use this workflow for greenfield projects and for brownfield edits that change t
 - [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, event-based, and complex gateways
+- [plugins/sequence-flows/](references/plugins/sequence-flows/) - control-flow edges, conditions, defaults, and diagram waypoints
+- [plugins/service-tasks/](references/plugins/service-tasks/) - service task wrappers and common service metadata boundaries
+- [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/) - human-in-the-loop tasks, outcomes, timeouts, and Action Center bindings
+- [plugins/queues/](references/plugins/queues/) - Orchestrator queue item creation and queue result handling
+- [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/) - agent job and A2A agent execution shells
+- [plugins/rpa-jobs/](references/plugins/rpa-jobs/) - Orchestrator RPA process job execution
+- [plugins/api-workflows/](references/plugins/api-workflows/) - API workflow invocation and response handling
+- [plugins/signals/](references/plugins/signals/) - signal definitions, throws, catches, waits, and broadcast semantics
+- [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

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

@@ -0,0 +1,28 @@
+# Agent Implementation
+
+This document defines the implementation boundary for agent tasks.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:serviceTask` wrapper for agent invocation.
+- Documented `Orchestrator.StartAgentJob` or `A2A.AgentExecution` `uipath:activity` shells.
+- 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 binding resolves before upload/run.
+- 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.

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

@@ -0,0 +1,29 @@
+# Agent Planning
+
+Use this reference when planning agent execution from BPMN.
+
+## 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
+
+- Service task wrapper with documented `Orchestrator.StartAgentJob` or `A2A.AgentExecution` shell.
+- 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.

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

@@ -0,0 +1,29 @@
+# API Workflow Implementation
+
+This document defines the implementation boundary for API workflow tasks.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:serviceTask` wrapper for API workflow execution.
+- Documented `Orchestrator.ExecuteApiWorkflowAsync` `uipath:activity` shell.
+- Request input CDATA using declared variables.
+- Output mappings for invocation ID, status, 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 variables.
+- Fire-and-forget versus wait behavior is explicit.
+- No private endpoint URLs, resource IDs, or exported payloads are committed.

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.
+
+## 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
+
+- Service task 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.

skills/uipath-maestro-bpmn/references/author/references/plugins/business-rules/impl.md

@@ -0,0 +1,28 @@
+# Business Rule Implementation
+
+This document defines the implementation boundary for business rule tasks.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:businessRuleTask` or service task wrapper when that is the local pattern.
+- Documented `Orchestrator.BusinessRules` `uipath:activity` shell.
+- Input CDATA for facts using declared variables.
+- Output mappings for rule result, matched rule, diagnostics, and outcome.
+- Gateway conditions that route by declared rule outputs.
+
+## CLI or operator-owned implementation
+
+The CLI or operator must resolve:
+
+- Real business rule resource identity, version, and binding metadata.
+- Dynamic input/output schemas.
+- Generated package metadata.
+
+## Validation expectations
+
+- Rule binding resolves before upload/run.
+- Facts match the resolved rule input contract.
+- Result variables exist and route expressions are assignment-free.
+- Fallback or manual review paths exist when rule failure is recoverable.

skills/uipath-maestro-bpmn/references/author/references/plugins/business-rules/planning.md

@@ -0,0 +1,29 @@
+# Business Rule Planning
+
+Use this reference when planning business rule execution from BPMN.
+
+## When to use
+
+- Evaluating rule tables or decision logic managed outside the BPMN diagram.
+- Routing based on a rule result.
+- Keeping business decisions separate from script code or gateway expressions.
+- Combining rule evaluation with HITL review, queueing, RPA, or API workflow calls.
+
+## Planning steps
+
+1. Identify rule resource, input facts, output shape, and decision routes.
+2. Decide whether rule failure should stop, retry, or route to manual review.
+3. Declare variables for facts, result, diagnostics, and selected outcome.
+4. Add a gateway after the rule task when result values drive routing.
+5. Use placeholder-safe bindings until the rule resource is resolved.
+
+## Model may draft
+
+- Service task wrapper with documented `Orchestrator.BusinessRules` shell.
+- Input/output mappings and post-rule gateway conditions.
+- Retry and boundary error paths.
+- Public-safe binding placeholders.
+
+## Stop conditions
+
+Stop before Operate when rule identity, input schema, output schema, version, or binding is unresolved.

skills/uipath-maestro-bpmn/references/author/references/plugins/call-activity-subprocess/impl.md

@@ -0,0 +1,29 @@
+# Call Activity and Subprocess Implementation
+
+This document defines the implementation boundary for call activities and subprocesses.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:subProcess`, event subprocess, and `bpmn:callActivity`.
+- Nested events, tasks, gateways, flows, and diagram planes.
+- Scoped variables and `uipath:mapping` for boundary data.
+- Boundary events, retries, and error mappings.
+- Placeholder-safe called element references when documented.
+
+## CLI or operator-owned implementation
+
+The CLI or operator must resolve:
+
+- Real called process, package, API workflow, agent, or solution resource identity.
+- Generated bindings and package metadata.
+- Dynamic input/output schemas for called resources.
+
+## Validation expectations
+
+- Sequence flows stay within subprocess scope.
+- Event subprocess start rules are satisfied.
+- Call activity inputs and outputs match declared contracts.
+- Nested visible elements have diagrams.
+- Called-resource bindings are resolved before upload/run.

skills/uipath-maestro-bpmn/references/author/references/plugins/call-activity-subprocess/planning.md

@@ -0,0 +1,29 @@
+# Call Activity and Subprocess Planning
+
+Use this reference when planning reusable or scoped process blocks.
+
+## When to use
+
+- Expanded subprocesses for local scoped work.
+- Event subprocesses for scoped exception handling.
+- Call activities for reusable processes or external workflows.
+- Isolating variables, retries, and boundaries.
+
+## Planning steps
+
+1. Decide whether the work is local subprocess content or a call to another reusable process.
+2. Define subprocess start/end behavior, variables, and mappings.
+3. Confirm whether nested content must render in Studio Web and needs its own diagram.
+4. Plan boundary events on the activity or subprocess.
+5. Keep sequence flows inside scope; use mappings for data crossing boundaries.
+6. Record unresolved called-resource bindings as placeholders.
+
+## Model may draft
+
+- `bpmn:subProcess`, event subprocess, and `bpmn:callActivity` structure.
+- Scoped variables, input/output mappings, loop metadata, and diagram geometry.
+- Boundary events and error paths.
+
+## Stop conditions
+
+Stop when a called process/resource is unknown, subprocess scope would be crossed by sequence flows, or input/output contracts are unclear.

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

@@ -0,0 +1,29 @@
+# Connector Implementation
+
+This document defines the implementation boundary for connector-backed BPMN elements.
+
+## Model-owned implementation
+
+The model may edit:
+
+- Standard BPMN wrapper elements around connector intent.
+- Variables and mappings that consume connector outputs.
+- Error, timeout, and fallback paths.
+- Diagram geometry.
+
+## CLI-owned implementation
+
+The CLI or registry-backed tool must generate:
+
+- `Intsvc.*` `uipath:activity` or `uipath:event` payloads.
+- Connector key, operation/event, object, and version context.
+- Connection binding expressions and `bindings_v2.json` resources.
+- Dynamic input/output schemas and generated output metadata.
+- Trigger property bindings for connector triggers.
+
+## Validation expectations
+
+- Every executable connector element has enriched context, inputs, outputs, and schemas.
+- Binding expressions resolve.
+- Required parameters and filters are present.
+- No tenant URLs, connection IDs, folder keys, or copied exported metadata are committed.

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

@@ -0,0 +1,33 @@
+# Connector Planning
+
+Use this reference for connector-backed activities and triggers. Connector execution is Integration Service-owned.
+
+## When to use
+
+- Connector activities.
+- Connector triggers.
+- Connector-backed waits.
+- Unified HTTP or authenticated HTTP through Integration Service.
+- Dynamic connector schemas.
+
+## Planning steps
+
+1. Identify connector, operation or event, object, filters, inputs, outputs, and failure behavior.
+2. Decide if the connector is a start trigger, intermediate wait, service task, or boundary behavior.
+3. Plan surrounding BPMN structure and variables.
+4. Record required operator choices: connection, folder scope, operation, filters, and output variable names.
+5. Leave enrichment to the CLI before validation for upload/run.
+
+## Model may draft
+
+- Placeholder BPMN wrappers with stable IDs and public-safe labels.
+- Surrounding flows, gateways, variables, and error paths.
+- Draft notes that describe connector intent.
+
+## CLI must provide
+
+- Connector metadata, operation/event metadata, connection binding, trigger properties, schemas, and generated binding resources.
+
+## Stop conditions
+
+Stop before Operate if the connector element is not CLI-enriched or if copied private connection metadata appears in the source.

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

@@ -0,0 +1,30 @@
+# Gateway Implementation
+
+This document defines the implementation boundary for BPMN gateways.
+
+## Model-owned implementation
+
+The model may edit:
+
+- `bpmn:exclusiveGateway`, `bpmn:inclusiveGateway`, `bpmn:parallelGateway`, `bpmn:eventBasedGateway`, and `bpmn:complexGateway`.
+- Incoming and outgoing `bpmn:sequenceFlow` references.
+- `default` attributes for exclusive and inclusive split gateways.
+- `bpmn:conditionExpression` on outgoing flows.
+- Gateway shapes and sequence flow edges.
+
+## Implementation rules
+
+- Store branch logic on outgoing sequence flows, not on the gateway element.
+- Use a leading `=` for runtime expressions where the frontend expects expressions.
+- Do not use assignment expressions in gateway conditions.
+- Prefer explicit default flows for fallthrough paths.
+- Use parallel gateways only when every branch should run or rejoin.
+- Use event-based gateways only when the next route is determined by the first event that occurs.
+
+## Validation expectations
+
+- Split gateways have the right number of outgoing flows.
+- Join gateways have the right number of incoming flows.
+- Defaults reference an outgoing flow from the same gateway.
+- Conditional branches reference declared variables.
+- Event-based gateway outgoing flows lead to valid catch events or receive tasks.

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

@@ -0,0 +1,31 @@
+# Gateway Planning
+
+Use this reference when planning BPMN routing, branching, and joining.
+
+## When to use
+
+- Exclusive, inclusive, parallel, event-based, or complex decisions.
+- Merging alternative paths.
+- Joining parallel or inclusive work.
+- Waiting for one of several events.
+
+## Planning steps
+
+1. Identify whether the gateway splits, joins, or does both.
+2. Choose the simplest gateway type that matches the business semantics.
+3. Put human-readable branch intent on outgoing sequence flows.
+4. Decide the default route for exclusive and inclusive splits.
+5. Decide join semantics for parallel and inclusive branches.
+6. Ensure no sequence flow crosses subprocess or participant scope.
+7. Plan diagram placement so conditions and routes are reviewable.
+
+## Model may draft
+
+- Standard gateway elements.
+- Outgoing sequence flow conditions and default flow references.
+- Public-safe IDs, names, and diagram geometry.
+- Text annotations that explain unresolved business decisions.
+
+## Stop conditions
+
+Stop for user input when branch conditions are ambiguous, defaults are unknown, or a join can deadlock because the triggering split semantics are unclear.