uipath-planner

# UiPath Planner — Design & Task Derivation Two jobs, one entry point: 1. **Design** — turn a Process Design Document (PDD) into an implementation-ready Solution Design Document (SDD). Select scope (single product or multi-project Solution), write the SDD. 2. **Plan** — derive the per-skill task list from an SDD (or a non-PDD request), route to specialists, emit live `TaskCreate` calls. Never execute the work. Outputs are SDD markdown, plan/tasks markdown, and live tasks — implementation always routes to a specialist. The skill has three paths, decided by the **Entry Guard**: - **Phase D — Design.** Input is a PDD, or an explicit "design / architect this" request. Author the SDD; the SDD write ends the turn, and Lane A continues on the next turn. See [sdd-generation-guide.md](references/sdd-generation-guide.md). - **Lane A — PDD-driven.** Input is an SDD with the `## Planner Handoff` marker (written by Phase D, or hand-written). Read it, derive tasks, emit live tasks. Zero to two user prompts. See [pdd-driven-lane-guide.md](references/pdd-driven-lane-guide.md). - **Lane B — Non-PDD.** No SDD; a non-PDD multi-project request. Elicit preferences, detect project type, write a plan, emit live tasks. 0–3 prompts (5-call cap). See [non-pdd-lane-guide.md](references/non-pdd-lane-guide.md). ## When to Use This Skill - User provides a **PDD or any process-knowledge source** — a PDD, Confluence page, BPMN model, meeting/Zoom transcript, SOP, or requirements doc (as PDF / Word / Markdown / `.txt` / `.bpmn` / pasted) — and asks to design or build from it → Phase D - User asks to **design / architect / generate an SDD** for a UiPath automation → Phase D - User provides an **SDD path** → Lane A - The request is **non-trivial** — spans **separate buildable projects** that each need their own specialist (a Flow orchestrating standalone RPA processes or agents that must themselves be built) → Lane B - The request is **ambiguous** — no single specialist clearly matches, or "what can I build?" **Skip this skill for single-project tasks** — load the specialist directly. A request is **single-project** (one specialist owns it end-to-end) even when it bundles several things *inside one project*: a Flow with script nodes plus an inline HITL approval step plus its own solution wrapper is **one** `uipath-maestro-flow` task. Inline nodes (HITL QuickForm, script, connector, inline agent) and solution scaffolding are author sub-steps the specialist performs itself — not separate skills to orchestrate. Counting them as distinct skills and emitting a plan is the most common mis-trigger. This skill is only for work spanning **separate buildable projects** (distinct `.uipx` projects), or for turning a PDD into an architecture. ## Critical Rules 1. **Plan & design only — never author automation code.** Outputs: SDD markdown (Phase D), plan/tasks markdown (Lanes A/B), and live `TaskCreate` calls. NEVER write XAML, C#, Python, JSON, or project/scaffold files. Implementation always routes to a specialist. (SDD/plan authoring is the *only* file authoring this skill does.) 2. **Run the Entry Guard first.** Inspect the input and route to Phase D / Lane A / Lane B before anything else. 3. **Select scope before designing architecture (Phase D) — and gate every product by platform constraints.** Single product (RPA Process/Library/Test Auto, Maestro Flow, Maestro BPMN, Case, Agents, Coded Apps, API Workflows) vs multi-project Solution determines the template(s) and project structure. Use the [Product Selection Guide](references/product-selection-guide.md): Constraint Gate → Level 1 → 1.5 (RPA sub-type) → 1.75 (Solution composition) → 2.5 (project decomposition). The delivery model (Cloud / Automation Suite / standalone — asked at Phase D entry) blocks unavailable products via [platform-availability-guide.md](references/platform-availability-guide.md); user-excluded products are never re-offered. 4. **The SDD is architecture only — no task lists.** Phase D produces the SDD (Project Structure, Data Definitions, Testing Strategy, …). Task derivation is Lane A's job. Never put Task 1 / Task N templates or *implementation* `TaskCreate` calls in the SDD. End the SDD with a `## Next Steps` section. (Progress-tracking `TaskCreate` calls are a separate, allowed use.) 5. **Write the `## Planner Handoff` header AND the `<!-- planner-handoff:v1 -->` marker into every SDD.** Load-bearing detection contract — the Entry Guard detects either signal (redundant on purpose). `Generated by: uipath-planner`. Fields: Status (draft → ready), Execution autonomy, Delivery model, SDD scope, the solution-root block (solution scope only: Solution root SDD, Solution ID, Project SDD role root|child, Independently executable: no on children — the root's Project Inventory + SDD Index are the sole executable entry; children and root share ONE canonical tasks file), Project list section, Tasks file, Generated by, Generation date, Template validation. The first incremental write stamps `Status: draft`; only after SME resolution AND the template-superset check does Phase D flip it to `ready` (+ `Template validation: passed`) — the marker identifies a planner SDD, the Status field says whether it is consumable. Lane A derives tasks from `ready` only (missing field = legacy → treat as ready). 6. **Honour the template section structure as a hard superset contract.** Write single-product scope to `<PROCESS_NAME_KEBAB>-sdd.md`; write Solution scope to a `<SOLUTION_NAME_KEBAB>-solution-sdd.md` overview plus one `<PROJECT_NAME_KEBAB>-sdd.md` per project. If the user specifies an output path for the SDD, use it instead of these defaults. After writing, diff the generated H2/H3 headings against the template TOC — the generated set MUST be a superset. A missing template-required H2 is an SDD defect, not an `[SME REVIEW]` item — regenerate it. 7. **Testing is mandatory and thorough — never offer "happy path only".** Phase D writes a full Testing Strategy section (happy path, edge cases, error scenarios, e2e for Master Projects). The plan adds a mandatory Testing task **per generation skill**, routing to that specialist's testing references — never describing the procedure inline. Implementation specialists may scope down at execution time; the SDD and plan do not. 8. **Route — do not redescribe.** The plan says WHICH skill to load and IN WHAT ORDER. It does NOT describe specialist-internal flows (target configuration, OR registration, XAML pipelines, HITL field/outcome schema, auth, testing procedures). For a HITL step, pass business intent only ("manager approves or rejects an expense; can add a reason if rejected") — never a field-level spec; the HITL specialist chooses the schema shape. 9. **Per-phase prompt budget.** Phase D runs under its own checkpoint model (see [sdd-generation-guide.md](references/sdd-generation-guide.md)) — no hard numeric cap. Lanes A and B each cap at **5 `AskUserQuestion` calls**. Ask **execution autonomy exactly once** (Phase D entry) and write it into the handoff header; Lane A reads it and never re-asks. Scope/UI answers resolved in Phase D flow forward via the SDD. 10. **Fill gaps with `[DEFAULT]` or `[SME REVIEW]` — never silently invent business rules.** `[DEFAULT]` for industry-standard patterns (retry counts, timeouts); `[SME REVIEW]` for business-knowledge gaps. Resolve `[SME REVIEW]` items with the user before writing. For Agent/Coded App gaps, use `AskUserQuestion` (proceed-with-gap-filling vs different product) — never auto-fallback. 11. **The terminal artefact of a Solution build is a packed `.uipx`.** The SDD's `## Next Steps` section points the user at the `uipath-solution` skill (`uip solution init` → `project add` per project → `resources refresh` → `pack`). A bare project folder is not the deliverable. Exception: when the Constraint Gate blocks Solutions for the delivery model — standalone, Automation Suite older than 2.2510, or a user exclusion — rewrite Next Steps to per-package Orchestrator publish routed via `uipath-platform`. 12. **Never copy SDD architecture into the plan, and never invent selectors or UI targets.** The plan references SDD section paths in skill prompts; it does not duplicate architecture content. Selectors require application inspection at development time — leave them for the specialist. ## Entry Guard Run this guard before anything else. ```text 1. No document path? - Explicit design/architect language ("design this", "architect this", "generate an SDD"), OR an inline-described process with enough detail to substitute for a PDD (process steps + applications + exceptions) → Phase D. A design/SDD request that is thin on process detail still routes to Phase D — elicit the missing steps/applications/exceptions via `AskUserQuestion` (Phase 1) rather than degrading to a Lane B plan. - Otherwise → Lane B. Lane B is the default for document-less multi-project requests. 2. Document path → read its first ~50 lines. - Contains `## Planner Handoff` OR `<!-- planner-handoff:v1 -->` → Lane A. (Either signal alone is sufficient — redundant on purpose.) - Reads as a PDD **or any process-knowledge source** — a process description (steps + applications + exceptions) in a PDD, Confluence page, BPMN model, meeting/Zoom transcript, SOP, or requirements doc; or a binary .pdf/.docx the user calls a PDD → Phase D. Less-structured sources (transcripts, thin wikis) still route to Phase D but trigger heavier Phase 1 elicitation. 3. Otherwise (no marker, ambiguous, or unparseable) — ask via AskUserQuestion: > What is the document at <path>? > 1. Process Design Document (PDD) — author the SDD (Phase D), then derive tasks > 2. Solution Design Document (SDD) — proceed with task generation (Lane A) > 3. Other context — read it; use its content to resolve Lane B elicitation > questions (skip any question it answers) and as plan input (Lane B) 4. Route per the choice. For an SDD with no handoff header, proceed with safe defaults — see pdd-driven-lane-guide.md Step 1 for the default set and how defaults are surfaced to the user. ``` Do not pattern-match on filename or extension alone; those are unreliable. The `## Planner Handoff` heading and the `<!-- planner-handoff:v1 -->` marker are the load-bearing detection contract — Phase D writes both deterministically; the guard detects either. ## Phase D — Design (summary) When triggered: input is a PDD, or an explicit design/architect request. Three phases; full detail in [sdd-generation-guide.md](references/sdd-generation-guide.md). All user questions use numbered-choice format. 1. **Phase 1 — PDD Analysis & Scope Selection.** Ask execution mode (Autonomous or Interactive) and delivery model (Cloud / Automation Suite / standalone) in one batched call — skip the delivery question when the PDD or request states it, or when the `uip login status` preflight resolves it from the session `BaseUrl`. Read the full PDD, extract structured information (including environment & constraint signals, as-is/to-be), synthesize the need profile (Step 3.5 — product picks reason from the need, not keywords), then run Constraint Gate → Level 1 (primary scope) → Level 1.5 (RPA sub-type) → Level 1.75 (Solution composition) → Level 2.5 (project decomposition). Step 2.5 runs an authenticated `uip` library search (CLI auth required). In Interactive mode, present a summary with the recommended scope at the top and alternatives below; in Autonomous mode, proceed. 2. **Phase 2 — Architecture Review.** Load the product-specific template. Generate the architectural core sections. Present for review in Interactive mode. 3. **Phase 3 — Full SDD Generation.** Generate all remaining sections including the thorough Testing Strategy. Resolve `[SME REVIEW]` items first (unresolved items carry recorded defaults and do not block `ready`; only architecture-blocking items keep `draft`). Write the `## Planner Handoff` header + marker with `Status: draft`. Write the SDD to disk — write early and append incrementally so a long turn still leaves a gradeable file; the LAST write flips `Status` to `ready` after the superset check passes. The SDD write is a **turn boundary**: in autonomous mode, end the turn after the SDD summary and continue into Lane A on the next turn (do not stack both phases in one turn). ## Lane A — PDD-driven (summary) When triggered: an SDD with the `Planner Handoff` marker is detected (or Phase D just wrote one). 1. Read the SDD's `## Planner Handoff` header. **`Status: draft` → refuse task derivation** (unfinished Phase D or a blocking SME item — offer resume or regenerate; missing field = legacy → ready; open default-carried SME items on a `ready` SDD travel into tasks as assumptions). Reuse the execution autonomy chosen in Phase D — do not re-ask. If `SDD scope: solution`, run the root algorithm: resolve the Solution root, verify every indexed child (exists, same Solution ID, ready), read every child's architecture, merge shared resources, emit ONE canonical tasks file (see pdd-driven-lane-guide Step 3). 2. If `<process>-tasks.md` already exists, ask `continue / regenerate` (1 prompt). See [plan-and-tasks-format.md → Regenerate logic](references/plan-and-tasks-format.md#regenerate-logic-pdd-driven-lane-only). 3. Parse the SDD project list section. Pick the multi-skill pattern. 4. Ask the UI batch (3 questions, 1 call) only if the SDD's Application Inventory lists UI applications and the answers aren't already resolved. 5. Derive tasks. Write `<process>-tasks.md`. 6. If `Execution autonomy: interactive` → `EnterPlanMode` for review. If `autonomous` → emit live tasks directly. 7. Emit `TaskCreate` calls + `addBlockedBy` edges. Hand off. Full procedure: [pdd-driven-lane-guide.md](references/pdd-driven-lane-guide.md). ## Lane B — Non-PDD (summary) When triggered: no SDD; a document-less multi-project request (the default route when no explicit design/architect language or inline-described process points to Phase D). 1. Step 1 — detect before asking (no prompts): read any provided context doc, filesystem detection (`Glob`/`Read`/`Grep` — cross-platform), multi-skill pattern classification, need-driven project-type inference, delivery-model resolution. 2. Step 2 — single-skill exit: one project owned end-to-end by one specialist → **stop Lane B**, load that specialist directly with the detected context (no plan file, no tasks). 3. Step 3 — batched elicitation: generation approach + execution autonomy + project-type fallback (when still vague) + delivery model (when a gated product is a candidate) in **one** `AskUserQuestion` call. Drop any question already resolved. 4. Step 4 UI batch — only when the plan includes UI automation in `uipath-rpa`. 5. Write `YYYY-MM-DD-<feature>.md` to `docs/plans/` (project) or `./plans/` (no project). Every task prompt embeds the plan path. 6. If explore-first → `EnterPlanMode`. If simultaneous → emit plan as text + live tasks. Full procedure: [non-pdd-lane-guide.md](references/non-pdd-lane-guide.md). ## Skill capability map High-level view of what each specialist owns. **Do not describe internal flows of any specialist in your plan** — each skill documents its own procedures and will drift out of sync if duplicated here. | Skill | What it owns | Handles auth? | Handles deploy? | |---|---|---|---| | `uipath-rpa` | RPA workflows (XAML and C# coded): create, edit, build, run, debug. Owns **all** UI automation authoring end-to-end, including live-app exploration and probing. | No (relies on Studio) | **No** — defer to `uipath-solution` for `.uipx` multi-project, `uipath-platform` for single non-solution packages | | `uipath-agents` | AI agents — code-based (LangGraph / LlamaIndex / OpenAI Agents) and low-code (`agent.json`) | Yes (`uip login`) | **Yes** — end-to-end | | `uipath-coded-apps` | Web apps (`.uipath/` dir): build, sync, package, publish, deploy | Yes (`uip login`) | **Yes** — end-to-end | | `uipath-functions` | Coded Functions — TypeScript (default), JavaScript, or Python (`uip function new -l ts / js / py`; typed I/O — Pydantic for Python) — atomic deterministic logic: transforms, custom-auth API calls, ERP/IS-connection queries. Runs serverless or on an RPA robot. Invoked from Maestro (Flow/BPMN), agents-as-tools, Orchestrator API. No LLM/agent loop (that → `uipath-agents`) | Yes (`uip login`) | **Yes** — `uip function pack/publish` | | `uipath-maestro-flow` | `.flow` files orchestrating RPA, agents, apps | Yes (`uip login`) | **Partial** — Orchestrator deploy of `.uipx`-wrapped solutions → `uipath-solution`; non-solution single package → `uipath-platform` | | `uipath-maestro-bpmn` | `.bpmn` files — standards-based BPMN 2.0 process orchestration (gateways, events, boundary timeouts, subprocesses, multi-instance) over RPA, agents, APIs, HITL. Authors its own inline userTask/HITL nodes. | Yes (`uip login`) | **Yes** — packages, uploads, publishes/deploys, and runs via `uip maestro bpmn`; Orchestrator deploy of `.uipx`-wrapped solutions → `uipath-solution` | | `uipath-maestro-case` | Case Management authoring (`caseplan.json` + generated BPMN) from an SDD | Yes (`uip login`) | **No** — deploys via `uipath-solution` (`.uipx`) | | `uipath-api-workflow` | API Workflows (JSON `document.dsl`): author, run locally (`uip api-workflow run`), connector activities | Yes (`uip login`) | **No** — `uip solution pack/publish` via `uipath-solution` | | `uipath-human-in-the-loop` | HITL node authoring — approval gates, escalations, write-back validation inside **Flow** projects. Coded-agent HITL → `uipath-agents`; BPMN / Case / RPA own theirs inline (userTask / task type / Action Center) | No (authoring only) | **No** — ships inside the host project | | `uipath-platform` | Auth (`uip login`), Orchestrator (folders, processes, jobs, machines, users, roles), resources (assets, queues, storage buckets + bucket files, libraries, webhooks, triggers), Integration Service (connectors, connections, activities, IS triggers), Data Fabric entities/records/files/choice-sets (`uip df`), traces, licensing | Yes (auth hub) | **Yes** — for non-solution single packages and Orchestrator-side post-deploy ops | | `uipath-ixp` | Document Understanding / IXP — extraction from semi-structured documents (invoices, forms): taxonomy, model, classify / extract / validate. Standalone project, or the extraction step a primary consumes | Yes (`uip login`) | **Partial** — model publish/tag via `uip ixp`; consumed by the host project | | `uipath-connector-builder` | Integration Service **custom connector** authoring (REST+JSON) on disk via `uip is connectors builder` — build a connector when the catalog has none for a required integration (needed by API Workflows / Maestro / Agents; RPA can call the API directly instead) | Yes (`uip login`) | **Yes** — import/publish is deployment (`uip is connectors`) | | `uipath-mcp-servers` | UiPath AgentHub MCP server registration (6 types: `uipath`, `coded`, `command`, `remote`, `swagger`, `platform`) and resource-tool authoring on `uipath`-type servers (`automation`, `agent`, `agentic-process`, `api-workflow`). Wraps Orchestrator resources, external HTTP MCP endpoints, OpenAPI specs, published coded agents, local subprocess commands, or first-party UiPath services as MCP tools. NOT for FastMCP / Python `mcp` SDK work. | Yes (`uip login`) | **Yes** — registration is deployment (posts directly to AgentHub) | | `uipath-solution` | `uip solution` lifecycle (init, pack, publish, deploy, activate) for `.uipx` solutions. Runs as the final skill in PDD-driven flows (deploy of `.uipx` solutions). | Yes (`uip login`) | **Yes** — for multi-project Solution (`.uipx`) deploys | ## Reference Navigation ### Phase D — Design | File | Purpose |