uipath-maestro-case

# UiPath Case Management Authoring Assistant Builds UiPath Case Management definitions from `sdd.md`. Generates `tasks.md` plan, then writes `caseplan.json` directly via per-plugin JSON recipes. > **Authoring invariant:** Never use mutating `uip maestro case` commands (`cases|stages|tasks|*-conditions ... add|update|remove`, including `tasks add-connector`) or explore them via `--help`. Use the CLI only for scaffolding, metadata reads, validation/debug, runtime operations, and solution sync/upload; consult [case-commands.md](references/case-commands.md) only when exact syntax is needed. CLI availability or a final `validate` requirement does not override this rule. When `sdd.md` is absent, **Phase 0** designs the case by best assumption from the request and documents, sweeps for other paths beyond the primary flow, and confirms it in ONE decision-first Case Review: case snapshot, primary journey, other paths, SLA responses, business rules/outcomes, resources, decisions, and review flags. The approval surface names every stage and task but omits data, variables, and task inputs/outputs; the template-complete `sdd.md` retains that technical detail and is written alongside the build as a reference artifact. When `sdd.draft.md` is present and the user asks to finalize it, stay in this skill: read the draft as the settled case design, normalize it to the Case Management SDD template, and do not hand off to `uipath-planner`. Complex / multi-product cases may still be designed with the same workflow; suggest `uipath-planner` only when the user explicitly requests planning across products. **Scope:** two journeys — **greenfield** (build a new case from `sdd.md`, user-provided or Phase 0-generated) and **brownfield** (targeted edits to an existing `caseplan.json` — see [references/brownfield.md](references/brownfield.md)). Editing a case that also lives in Studio Web? Brownfield pulls the current server state first (`uip solution download` / `solution projects resync`) so re-publish can't silently clobber server-side changes — see [brownfield.md § Pull latest first](references/brownfield.md#pull-latest-first-before-editing). ## When to Use This Skill - User provides `sdd.md` and wants Case Management project built - User asks to create new case management project but has no `sdd.md` (Phase 0 interview generates one) - User asks to create new case management project or definition - User asks to generate implementation tasks from `sdd.md` or convert spec to plan - User asks to edit, modify, or update an existing `caseplan.json` (add/remove a stage or task, change a condition, swap a trigger) — targeted edits skip planning; see [references/brownfield.md](references/brownfield.md) - User asks about case management JSON schema — nodes, transitions, tasks, rules, SLA - User wants to manage runtime case instances (list, pause, resume, cancel) — see [references/case-commands.md](references/case-commands.md) **Do not use for:** `.xaml` → `uipath-rpa`. `.flow` → `uipath-maestro-flow`. Standalone agents/APIs/processes outside case context → corresponding UiPath skill. ## Critical Rules 1. **Phase 0 best-assumption design when `sdd.md` absent.** Listen and ground, then decide every open field per the assumption playbook — inform, don't interrogate: every assumption, override, and resource decision is disclosed in the single confirmation's `Decisions I Made` table. The confirmation is a decision-first **Case Review** with exactly eight sections: Case Snapshot, Primary Journey, Other Paths Considered, SLA and Escalations, Rules and Outcomes, Resources and Integrations, Decisions I Made, and Review Flags. It names every stage and task with task type, activation/grouping, required status, routing/outcome, and SLA context; it deliberately omits the data contract, variables, and task inputs/outputs, which remain complete in `sdd.md`. It must be complete enough to approve the business behavior without opening `sdd.md`; do not defer a missing business decision by saying it will be in the document. This structured Case Review is the only valid plan-first approval surface for Phase 0; a generic "Build Plan" / "Approve this plan" checkpoint does not count, and a user "Yes" to that checkpoint is not a Build answer. Question budget: one clarifying call (only for an empty request, contradictory inputs, user-requested questions, or no source signal for other paths) plus ONE confirmation ([phase-0-interview.md § Confirm](references/phase-0-interview.md#confirm--the-single-checkpoint)). If `sdd.draft.md` exists and the user asks to finalize it, use the direct draft-resumption path in this skill: read the draft and SDD template, render the final `sdd.md` from the Case Management template, do not spawn subagents, do not preload planning/plugin references, and never delegate to `uipath-planner`. **Direct finalization repairs schema-required companion rules as row replacements, not extra routes: for an authored `user-selected-stage`, replace each eligible origin's existing `required-tasks-completed | exit-only | Yes` row with the single row `required-tasks-completed | wait-for-user | Yes`; never retain the old completion row or add a `Marks Stage Complete: No` duplicate.** `wait-for-user` exposes the picker; it does not add automatic event/SLA/decision routing. On a Build answer, render `sdd.md` from the in-memory model batched with the first build actions — the file MUST pass the template-conformance gate in `phase-0-interview.md`; a summary SDD is invalid even if `caseplan.json` later validates. Explicit sign-off requests add one approval prompt; design-only requests save `sdd.md` and stop; draft requests save `sdd.draft.md` and stop. When the prompt explicitly says to get/save a draft and stop, that request is already the save instruction: show the Case Review, write `sdd.draft.md`, and stop without asking for another approval. When the prompt explicitly asks to produce `sdd.md` plus `tasks/tasks.md` and stop before `caseplan.json`, use the bounded no-build fast path in `phase-0-interview.md`: after the Case Review, write the full-template `sdd.md`, create `tasks/`, write compact `tasks/tasks.md`, and stop; do not read planning/plugin references, tenant discovery sources, or the full SDD finalization checklist. Never overwrite an existing `sdd.md`. 2. **sdd.md is sole input post-Phase-0 — across sessions.** When user-provided, or in any later session, re-run, or staleness recovery (context compaction), trust `sdd.md` as written; the skill does not validate or gap-fill it. Within the session that just confirmed the design, the in-memory model that rendered `sdd.md` is the same content and drives the build directly ([phase-0-interview.md § Build start](references/phase-0-interview.md#build-start--sdd-written-alongside-the-build)) — do not re-read the just-written file. If a build-phase ambiguity arises, use AskUserQuestion — never infer silently. 3. **PHASE 1 HARD GATE — fresh registry before planning, pulled at most once per session.** Run `uip login status --output json`, then `uip maestro case registry pull`, before cache inspection, carryover reuse, resource resolution, or any Phase 1 artifact write — **same-session fast path:** when Phase 0's pull already succeeded in THIS session and `sdd.md` was just rendered from the confirmed in-memory model, reuse that cache and skip the re-pull. Any doubt runs the gate in full: user-provided SDD, cross-session resume, context compaction, a Phase 0 pull that failed or never ran, or missing cache files. **Plan-only exception:** if the user explicitly asks to stop at `sdd.md`/`sdd.draft.md`/`tasks.md` and not create `caseplan.json`, do not run tenant registry, connection, schema, or user-discovery commands; preserve concrete intended resource/system names, mark identities `resolve at build`, and report that resource wiring is deferred to the later build run. Trust the SDD as written; the pull refreshes the local discovery cache and does not validate or override the SDD. **Cache-state rule:** before a successful pull (this session), a missing cache directory/file is a failed refresh precondition — never a zero-match result. Only after a successful pull may an empty exact-name match set (or a still-absent type index) enter the normal empty-lookup flow. Login/pull failure → surface it and stop Phase 1. Discovery reads `~/.uip/case-resources/<type>-index.json` directly because `registry search` has known gaps (esp. action-apps). Phase 0 pulls lazily only for build runs: the same login/pull chain starts in the background only when the case first shows tenant-bound work and a later build may need identities, followed by one light name-match pass — no schema discovery, no resource prompts; unclear items defer to this gate as `resolve at build`. See [references/registry-discovery.md](references/registry-discovery.md). 4. **`--output json` on every parsed read.** 5. **Follow plugin per node type.** Open matching `planning.md` during planning + `impl-json.md` during execution. Never guess JSON shapes from memory. 6. **`tasks.md` declarative and lossless only.** No shell commands inside. Field names use plain identifiers (e.g., `type:`, `displayName:`, `lane:`), not CLI flag syntax. One T-entry per sdd.md declaration — every stage, task, trigger, condition, SLA rule, **variable, and argument** gets own T-number, even when value looks like default (`current-stage-entered`, `case-entered`, `exit-only`, `is-interrupting: false`, `runOnlyOnce: true`, `marks-stage-complete: true`). Never group, never silently omit. **An explicit stage/task entry or exit rule in a supplied or approved SDD is authoritative: planning and implementation preserve that exact rule and its selectors, even when a different rule would normally be inferred from task proximity or list order.** Preserve every stage/task/SLA `Design Rationale` and condition routing/activation rationale as `rationale:` on the matching T-entry; rationale is reviewer/audit context and never changes the executable JSON shape. Preserve every SDD Inputs row with its declared binding mode and value. A JSON object literal stays literal through both handoffs: record the exact JSON in `tasks.md`, then write either the native object or its JSON-encoded string to `input.value`; never add `=js:` or `=jsonString:` unless the SDD itself explicitly uses that prefix. Project every task/rule Outputs table row through the common grammar in [`plugins/variables/io-binding/planning.md`](references/plugins/variables/io-binding/planning.md#sdd-outputs-table-to-tasksmd-projection-mandatory), then preserve each resulting `outputs:` item **with its operator and both operands unchanged**. SDD Outputs rows require `->` or `=`; a bare `tasks.md` output is generated only from resolved-schema discovery and is never authored as an SDD row. SDD table placeholders such as a `—` Field are not operands and never appear in `tasks.md`. In particular, `greeting -> greeting` is NOT equivalent to schema-discovered bare `greeting`: the former extracts into the predeclared case variable and requires `originalVar`; the latter auto-mints a task-local output. Never simplify an equal-name `->` row. **When an sdd.md row's format is unrecognized, ambiguous, or cannot be categorized — invoke AskUserQuestion before skipping. Silent omission is forbidden.** Always regenerate from scratch (greenfield/planning only — brownfield targeted edits mutate in place and preserve IDs; see [references/brownfield.md](references/brownfield.md)). **Every §4.6 task T-entry carries its own `activation-mode:` and `entry-rule:` lines — a separate §4.7 `rule-type:` entry does not satisfy this.** **Every task T-entry heading quotes the task's display name** in the exact form `## T<n>: Add <type> task "<name>" to "<stage>"` (e.g. `## T08: Add wait-for-timer task "First Step" to "Process"`) — an unquoted or reworded heading (e.g. `## T08: Task First Step`) breaks plan addressability and fails plan validators even when `caseplan.json` itself is correct. See [`references/planning.md` §4.0](references/planning.md) and the [Plan-shape gate](references/planning.md#step-5--finalize-tasksmd-auto-proceed-to-phase-2). 7. **`tasks.md` gate — auto-approved by default, opt-in stop.** Phase 1 auto-proceeds into Phase 2 Prototyping with no AskUserQuestion sign-off; treat the plan as approved. **Stop after `tasks.md` only when the request explicitly asked for a plan-only / review-first run** (e.g. "just the plan", "Phase 1 only", "stop after tasks.md for review", "don't build the case yet") — then report the plan and do NOT proceed to Phase 2. Re-read `tasks.md` before executing. 8. **Unresolved resource → placeholder, never fabricate IDs.** Keep `<UNRESOLVED: ...>` markers in `tasks.md`. Placeholder **task**: node with `type` + `displayName` + structural fields, `data: {}`; conditions still reference the TaskId. Placeholder **event trigger**: node with render fields + `data.inputs: { serviceType: "Intsvc.EventTrigger" }` only (no other `data.inputs` keys); `entry-points.json` entry appended. No trigger-edge is created (Rule 20). See [references/placeholder-tasks.md](references/placeholder-tasks.md) and [references/plugins/triggers/event/impl-json.md § Placeholder fallback](references/plugins/triggers/event/impl-json.md). 9. **Persist every registry resolution to `registry-resolved.json`** — one object per task with exact keys `stage`, `task`, `taskType`, `cacheFile`, `searchQuery`, `matches`, `selected`, and `rationale` (plus resolved I/O/review metadata when applicable). `stage` + `task` associate the audit entry to one SDD declaration; `cacheFile` is the basename actually searched; `matches` is the full exact-name match set from the cache refreshed in Rule 3, not a summary. Use the authoritative SDD fields as the search and selection contract; record `selected` from that match set, or `null` after a genuine empty lookup. 10. **Cross-task refs:** plan as `"Stage Name"."Task Name".output_name`. Resolve both whole-value `<-` and in-expression `$xref` through the common output-reference-ID algorithm in [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md#output-reference-id-authoritative): use the source output's `.id`; only a custom `=` output, which intentionally has no `.id`, resolves through its verified root companion's `.id`. Never use a reassigned output's `.var` as the source reference ID — it points at the target Case variable and can differ from the collision-safe source `.id`. Discover output names via `uip maestro case spec` (connector tasks) or `uip maestro case tasks describe` (non-connector tasks) — never fabricate. **Inside** a larger `=js:` expression (composite payload, condition, SLA), use the in-expression marker `vars.$xref('Stage','Task','output')` instead — resolved at Step 11.5. See [references/bindings-and-expressions.md](references/bindings-and-expressions.md) and [`plugins/variables/io-binding/impl-json.md`](references/plugins/variables/io-binding/impl-json.md). 11. **Build-review preference decides the Phase 2 → Phase 3 boundary — captured ONCE, up front, never asked mid-build.** Capture it at journey start: greenfield-with-interview folds it into the single confirmation's Build options (`Build it — straight through` / `Build it — pause at the build preview` — [phase-0-interview.md § Confirm](references/phase-0-interview.md#confirm--the-single-checkpoint)); greenfield-with-provided-SDD asks it once right after the roadmap; non-interactive runs and resumed runs with no recorded preference default to **straight-through** (no mid-build publish — Phase 5 stays the only publish point and stays gated). At the boundary, try `validate --skeleton-v2` first; fall back once to legacy `--skeleton` **only** when the parser response names `--skeleton-v2` as unknown or unsupported (typically `ErrorCode: invalid_argument` and exit 3). Exit 3 alone is not enough. A genuine validation failure means v2 ran — report it and do not hide it with a fallback. Name the selected profile in the counts summary; the gate is advisory and never halts on validation findings. Then: **straight-through** → continue into Phase 3 with no prompt, the summary line doubling as the milestone narration; **pause-at-preview** → follow the publish-for-review contract in [`references/phased-execution.md`](references/phased-execution.md) (AskUserQuestion `Publish for review` / `Skip publish and continue` / `Abort`; on publish, print `DesignerUrl` as plain text BEFORE the follow-up prompt — never only inside the question body). Hard stops that are NEVER bypassed regardless of preference: Phase 4 retry exhaustion (`Retry with fix` / `Pause for manual edit` / `Abort`), Phase 5 entry (`Publish to Studio Web` / `Skip to Debug`), and Phase 6 entry (`Run debug session` / `Done`). Full contract in [`references/phased-execution.md`](references/phased-execution.md). 12. **Never run `uip maestro case debug` automatically.** Executes case for real — emails, messages, API calls. Explicit user consent only. 13. **All skill artifacts: Read + Write/Edit only.** Applies to `caseplan.json`, `sdd.md`, `sdd.draft.md`, `tasks.md`, `tasks/registry-resolved.json`, `tasks/trigger-spec-cache.json`, `tasks/spec-cache.<elementId>.json`, `bindings_v2.json`, `id-map.json`, `entry-points.json`, `build-issues.md`. No `python`, `node`, `jq`, `sed`, `awk`, or scripts that open/parse/modify/save these files. **Shell filesystem commands may not create, replace, rename, or relocate an artifact** — `cp`, `mv`, `install`, and `rsync` are forbidden for these files, including copying or renaming `sdd.draft.md` to `sdd.md`. **Specifically forbidden** (common slip): `node -e "...fs.writeFileSync..."`, `node -e "...fs.readFileSync..."`, `node -e "..." > <artifact>`, `jq '...' <artifact> > <artifact>`, `python -c "...open(...,'w')..."`, `sed -i`, `awk -i inplace`, or any shell redirection (`>`, `>>`, `| tee`) onto a skill artifact regardless of interpreter. **Writing a helper script under `/tmp` or anywhere else to assemble a skill artifact is also forbidden** — the build-assembler pattern (`/tmp/build-caseplan.js`, `/tmp/gen-tasks.py`, etc.) is the same Rule 13 violation as inline `node -e`, regardless of "mechanical copy" or "avoid Read+Write churn" framing. If `caseplan.json` exceeds ~30KB and a single Write feels too large, split into the Phase-2-preview-then-Phase-3-detail cadence (per [case-editing-operations.md § Per-section batch write contract](references/case-editing-operations.md#per-section-batch-write-contract--canonical)) — never via helper script. **The `node -e ... fs.*` ban is not scoped to the artifact list — it applies to ALL file reads in this skill, including resource cache reads from `~/.uip/case-resources/`. Use `cat ... | python3 -c "..."` or the `Read` tool for cache lookups.** Bash subprocesses OK ONLY for UUID v4 generation (`node -e "console.log(crypto.randomUUID())"` for `operate.json.projectId` and `entry-points.json` `uniqueId` — subprocess MUST NOT `require('fs')` or use redirection), CLI metadata fetches, validate, debug, and solution scaffold/upload. **Prefixed IDs (`Stage_`, `t`, `Rule_`, etc.) are picked inline by the agent — no subprocess.** See [references/case-editing-operations.md § Tool usage](references/case-editing-operations.md#tool-usage--mandatory).