feat(hitl-skill): add Case Management surface — hitl-casetask-action.md + SKILL.md routing

[dushyant-uipath]

Summary

• references/hitl-casetask-action.md (new): The Case equivalent of hitl-node-quickform.md. Documents the action task JSON for Case HITL — generic (no app) and app-based flavors, uip case hitl add CLI opt-in, field reference, assignee handling, and downstream output access.
• SKILL.md: Add Case surface detection in Step 1 (detect caseplan.json), Case write path in Step 5, and a reference entry at the bottom.

Pattern followed

Mirrors how plugins/hitl/impl.md in the flow skill points to hitl-node-quickform.md in this skill. The case skill's action/planning.md and action/impl-json.md reference hitl-casetask-action.md (in the companion case skill PR #540).

CODEOWNERS

/skills/uipath-human-in-the-loop/ — @dushyant-uipath

Related

• Case skill PR: feat(case-skill): document CLI mutation commands + hitl add opt-in #540 (adds references to this doc from case/action task docs)
• CLI PR: https://github.com/UiPath/cli/pull/1207 (uip case hitl add command)

---

Update — feat(hitl-skill): add Case QuickForm path (commit 1229060)

What's new

• Path 1 — QuickForm (inline schema) added to hitl-casetask-action.md alongside the existing Generic and App-based paths. Mirrors the Flow QuickForm shape (data.formType: "quick" + data.schema.{fields, outcomes}) but adapted to the case action task envelope. Uses =vars.<varId> bindings (case form), not =js:$vars.… (flow form).
• Build-time vs design-time callout: design time = the JSON in caseplan.json round-tripped by Studio Web's case designer; build time = uip maestro case validate + Action Center renders the form at runtime. Both must round-trip the same JSON.
• SKILL.md Surface: Case now presents three options (QuickForm / Generic / App-based) with QuickForm as the default. Step 4b (Schema Design Resilience) retitled to apply to both Flow and Case QuickForm.

Removed (CLI cleanup)

• All references to uip maestro case hitl add stripped. That command is not documented in uipath-maestro-case/references/case-commands.md (the authoritative case CLI reference), which lists only validate, pack, debug, tasks describe, registry, process, job, instance. The references were inherited from a planned-but-unshipped CLI (originally noted as "ships in UiPath/cli PR #1207").
• Case surface is now correctly documented as direct-JSON-only. uip maestro case validate remains as the only uip maestro case CLI used by this skill on the Case surface (build-time check).

Safety net — auto-revert + App-based fallback (commit fdc035f)

If uip maestro case validate rejects the QuickForm shape on a runtime that doesn't yet support it, the agent snapshots caseplan.json before writing, auto-reverts on failure, surfaces the validator error to the user verbatim, and offers to retry via the proven App-based path with the same fields/outcomes — never leaves the user with a half-written invalid caseplan.json.

JSON shape (proposed — needs runtime confirmation)

{
  "id": "ta1b2c3d4",
  "type": "action",
  "data": {
    "taskTitle": "Please review this invoice",
    "priority": "Medium",
    "assignmentCriteria": "user",
    "recipient": { "Type": 2, "Value": "approver@company.com" },
    "formType": "quick",
    "schema": {
      "id": "<uuid>",
      "fields": [
        { "id": "amount", "label": "Amount", "type": "number", "direction": "input", "binding": "=vars.amountVar" },
        { "id": "decision", "label": "Decision", "type": "text", "direction": "output", "variable": "decision", "required": true }
      ],
      "outcomes": [
        { "id": "approve", "name": "Approve", "isPrimary": true,  "outcomeType": "Positive", "action": "Continue" },
        { "id": "reject",  "name": "Reject",  "isPrimary": false, "outcomeType": "Negative", "action": "End" }
      ]
    }
  }
}

Confirmation needed: this JSON shape mirrors the Flow QuickForm node closely, but no precedent exists in the case management skill yet. When the case-management runtime support lands, verify field names against the actual validator (e.g. formType vs taskFormType vs inputs.type) and adjust if needed.

Test coverage

No automated test for Case QuickForm yet. The uipath-human-in-the-loop skill currently has 22 tests, all targeting the Flow surface. Follow-up: add tests/tasks/uipath-human-in-the-loop/smoke_09_case_quickform.yaml once the JSON shape is confirmed by the runtime team.

[github-actions]

Claude finished @dushyant-uipath's task in 1m 33s —— View job

---

PR Review: feat(hitl-skill): add Case Management surface

• Read review criteria and project conventions
• Read full diff and changed files
• Check skill structure and frontmatter
• Verify links resolve to existing files
• Check for cross-skill references and secrets
• Check CODEOWNERS
• Post review findings

---

Summary

Adds Case Management as a new HITL surface: a new reference doc (hitl-casetask-action.md) documenting the action task JSON for Case HITL, and routes to it from SKILL.md Step 1 detection table and Step 5 write path. The reference covers generic and app-based task flavors, CLI opt-in, field reference, and downstream output access.

Change-by-Change Review

1. skills/uipath-human-in-the-loop/references/hitl-casetask-action.md (new, +209 lines)

Severity: High (1 issue), Medium (2 issues)

High — Cross-skill reference (line 114). The file links to ../../../uipath-maestro-case/references/plugins/tasks/action/impl-json.md#step-1--root-level-bindings — this is a direct cross-skill reference that violates the repo's self-containment rule. While the file does exist on disk, skills must not reference other skill folders. The binding construction rules need to be inlined here (or a self-contained summary provided), with the cross-skill link removed.

For binding construction rules, see [action/impl-json.md](../../../uipath-maestro-case/references/plugins/tasks/action/impl-json.md#step-1--root-level-bindings) in the case skill.

Fix this →

Medium — Priority value inconsistency. The field reference table (line 127) lists four values: "Low", "Medium", "High", "Critical". But the CLI flags table (line 173) only lists three: Low, Medium, High. And the conversation question (line 16) also only lists three. If "Critical" is valid for JSON but not for the CLI, that should be noted explicitly — otherwise the agent may try --priority Critical and get an error. Similarly the default differs: field reference says "Medium", CLI says "Low", SKILL.md Step 5 says Low|Medium|High.

Medium — Step 1b CLI commands look speculative. Lines 33–35 show uip maestro case stages get and uip maestro case cases get — these are different from the uip maestro case hitl add command documented later. Verify these subcommands actually exist in the CLI. If they don't ship until a later PR, add an availability note like the one on line 180.

2. skills/uipath-human-in-the-loop/SKILL.md (modified, +26 lines)

Severity: Medium (1 issue), Low (1 issue)

Medium — Detection table adds Case row but no find command for caseplan.json. Step 1 (lines 62–71) has find commands for .flow, agent.json, and .bpmn — but no corresponding find command was added for caseplan.json. The detection table at line 76 references caseplan.json but the agent has no instruction to search for it. Add:

# Check for caseplan.json (Case Management project)
find . -name "caseplan.json" -maxdepth 4 | head -3

Fix this →

Low — Section title says "Find the Flow File" but now covers Case. Step 1 header (line 58) is Step 1 — Detect the Surface and Find the Flow File. Since this step now covers Case plans too, the title is slightly misleading. Consider: Step 1 — Detect the Surface.

What's Missing

• Missing find command for caseplan.json in Step 1 detection block (covered above as Medium)
• No Case-specific Critical Rules. The existing Critical Rules (lines 31–41) are all Flow-specific (.flow file, workflow.nodes, uip maestro flow validate). Case surface has different validation (uip maestro case validate) and different write targets (stage.data.tasks[]), but no Critical Rules cover these. Consider adding at least: "Validate Case plans with uip maestro case validate, not uip maestro flow validate" and "Write task into stage.data.tasks[lane][], not workflow.nodes."
• No e2e test task for Case surface. Existing tests all target the Flow surface. No smoke or e2e task covers the new Case path. (Flagged as Medium — consistent with most skills not yet having full test coverage for all surfaces.)

Area Ratings

Area	Status	Notes
Frontmatter	OK	No changes to frontmatter; existing frontmatter valid
E2E Tests	Issue	No test task for the new Case surface
Skill Body	Issue	Missing find command for caseplan.json in Step 1
References & Assets	Issue	Cross-skill link in hitl-casetask-action.md:114 violates self-containment
Repo Hygiene	OK	CODEOWNERS entry exists, no secrets, changes scoped to this skill

Issues for Manual Review

• CLI command accuracy: uip maestro case stages get, uip maestro case cases get, uip maestro case hitl add, and uip maestro case validate are all referenced but the CLI PR (#1207) is noted as in-flight. Verify these subcommand names and flags match the actual CLI implementation.
• shouldRunOnlyOnce field appears in the app-based JSON example (line 97) but is absent from the field reference table. Confirm whether this is a valid field for Case action tasks.

Conclusion

Request changes. The new reference doc is well-structured and follows the existing pattern from the Flow surface. Three items need attention before merge:

1. Must fix (High): Remove the cross-skill link at hitl-casetask-action.md:114 — inline the binding construction rules or provide a self-contained summary
2. Should fix (Medium): Add the find command for caseplan.json to Step 1's detection block
3. Should fix (Medium): Reconcile the priority value inconsistency ("Critical" in field reference vs absent from CLI and conversation prompts)

---

[github-actions]

Claude finished @rohan-uip's task in 3m 39s —— View job

---

Coder-eval task lint (advisory)

3 task YAMLs changed; 0 Critical, 1 High, 1 Medium, 1 Low, 0 OK.

Rubric: .claude/commands/lint-task.md. This check is advisory and never blocks merge.

Evidence of passing run

❌ High — PR body does not claim the changed tasks have been run and passed. The body states "No automated test for Case QuickForm yet" and "Follow-up: add smoke_09_case_quickform.yaml once the JSON shape is confirmed by the runtime team" — the tasks were added but no passing-run claim accompanies them. Please edit the PR description to add a line like: Ran skill-hitl-smoke-case-quickform locally and it passed.

Per-task lint

tests/tasks/uipath-human-in-the-loop/quality_12_case_path_selection.yaml — verdict: High

Issues:

• [High] Prompt over-specification: CRITICAL CONSTRAINTS at line 111 says "The chosen path (QuickForm) does NOT need root-level bindings" — this leaks the expected answer for a test whose stated purpose is to verify the agent reads the path-selection table and picks the right path. Any agent reading the constraints knows the answer without consulting the skill.

Suggested fixes:

• Remove the parenthetical (QuickForm) from the constraint at line 111. Rewrite as: "The correct path for this scenario does NOT need root-level bindings. Leave root.data.uipath.bindings as an empty array []." This preserves the guardrail without leaking the answer.
• Alternatively, move the binding constraint to a post-hoc criterion (a run_command negative check like the existing grep -L at line 168) instead of a prompt instruction.

tests/tasks/uipath-human-in-the-loop/smoke_09_case_quickform.yaml — verdict: Low

Issues:

• [Low] Prompt over-specification: line 109 teaches the =vars.<varId> binding syntax ("Bind input fields to case variables with =vars.<varId> only"). The skill's hitl-casetask-action.md should be what teaches this; prescribing it in the prompt means an agent could produce correct bindings without loading the skill reference.

Suggested fixes:

• Drop the binding-syntax instruction at line 109. The constraint at lines 107-108 ("Do NOT use any =bindings.<id> references") is a valid guardrail against the wrong path; the positive =vars.<varId> teaching should come from the skill.

tests/tasks/uipath-human-in-the-loop/smoke_10_case_generic.yaml — verdict: Medium

Issues:

• [Medium] Prompt over-specification: lines 94–98 prescribe the exact field set for a Generic action task ("must contain ONLY taskTitle and priority... Do NOT add actionCatalogName, name, folderPath, formType, schema, inputs, or outputs"). The skill should be teaching which fields belong to the Generic path; listing them in the prompt is a recipe.
• [Medium] Meaningful coverage: success criteria are overwhelmingly negative — two run_command checks verify wrong fields are absent (lines 121–134), but only one file_contains (line 112) validates correct structure, and it only checks for the taskTitle string. No criterion validates that priority is set, that the task was inserted into Stage_aB3kL9.data.tasks[] (not at root), or that the task id follows the expected format.
• [Medium] Could pass for wrong reason: an agent that writes the seed caseplan.json and appends {"type": "action", "data": {"taskTitle": "Review and approve this expense claim"}} anywhere in the file passes all criteria — no formType, no schema, no actionCatalogName, no resource: app, and the taskTitle string is present. The negative-only checks don't verify the task is structurally complete or correctly placed.

Suggested fixes:

• Trim the field-list constraint (lines 94–98) to just the negative guardrail: "Do NOT add actionCatalogName, formType, schema, or inputs/outputs blocks." Let the skill teach what Generic does include.
• Add a file_contains check for "priority": "Medium" to validate the priority field was set.
• Add a json_check or run_command criterion that verifies the action task object appears inside a tasks array (e.g., grep -P '"tasks"\s*:\s*\[' caseplan.json paired with a check that the task is nested under the stage, not free-floating).

Within-PR duplicates

• [Medium] Cluster: quality_12_case_path_selection.yaml, smoke_09_case_quickform.yaml — both create a seed caseplan.json and add a QuickForm action task to the same stage. The caseplan.json scaffold is nearly identical (same node IDs, same structure, different variable names). quality_12 adds a path-selection choice.json aspect but ~70% of its criteria overlap with smoke_09's caseplan.json structural checks. Consider: (a) making quality_12 check only the path selection (choice.json + one file_contains confirming formType) and not re-validate the full QuickForm structure, or (b) having quality_12 seed with a pre-authored QuickForm task and test selection reasoning only.

Conclusion

⚠ 3 task(s) have issues, max severity High. Advisory only — not blocking merge.

The main action item is the answer leak in quality_12 (line 111 says "QuickForm" in a test designed to check if the agent picks the right path). The smoke_10 negative-only criteria are a secondary concern — adding one or two positive checks would meaningfully strengthen that test. The missing passing-run claim in the PR body is expected given the author's note that the JSON shape awaits runtime confirmation, but should be updated once confirmed.

---

[github-actions]

Claude finished @rohan-uip's task in 3m 6s —— View job

---

Coder-eval task lint (advisory)

3 task YAMLs changed; 0 Critical, 1 High, 0 Medium, 2 Low, 0 OK.

Rubric: .claude/commands/lint-task.md. This check is advisory and never blocks merge.

Evidence of passing run

❌ High — PR body does not claim the changed tasks have been run and passed. The body states "No automated test for Case QuickForm yet" and "Follow-up: add smoke_09_case_quickform.yaml once the JSON shape is confirmed by the runtime team" — the tasks were added in a later commit but the PR body was never updated with a passing-run claim. Please edit the PR description to add a line like: Ran skill-hitl-smoke-case-quickform locally and it passed.

Per-task lint

tests/tasks/uipath-human-in-the-loop/quality_12_case_path_selection.yaml — verdict: High

Issues:

• [High] Prompt over-specification: line 111 says The chosen path (QuickForm) does NOT need root-level bindings — the parenthetical (QuickForm) leaks the expected answer for a test whose stated purpose (line 3–7) is to verify the agent reads the path-selection table and picks the right path. Any agent reading the constraints knows the answer without consulting the skill.
• [Low] Meaningful coverage: no criterion validates the task was inserted into Stage_aB3kL9.data.tasks[] (could appear anywhere in caseplan.json). No check for assignee (data-enrichment-team) or priority (Medium) fields, both specified in the prompt at line 96.

Suggested fixes:

• Remove the parenthetical (QuickForm) from line 111. Rewrite as: "The correct path for this scenario does NOT need root-level bindings. Leave root.data.uipath.bindings as an empty array [] — do NOT add any entries with \"resource\": \"app\". The form schema lives inline in data.schema." This preserves the guardrail without leaking the answer.
• Add a file_contains check on caseplan.json for "data-enrichment-team" and "Medium" to validate assignee and priority were set.
• Add a run_command criterion that verifies the task appears inside a tasks array (e.g. grep -P '"tasks"\s*:\s*\[' caseplan.json or a jq check that .nodes[] | select(.id=="Stage_aB3kL9") | .data.tasks | length > 0).

tests/tasks/uipath-human-in-the-loop/smoke_09_case_quickform.yaml — verdict: Low

Issues:

• [Low] Meaningful coverage: no criterion validates the proposed input fields (invoice ID, total amount) appear in the recommendation's inputs array. An agent could emit "inputs": [] with the right case_path and outcomes and still pass.

Suggested fixes:

• Add a file_contains check on recommendation.json for one of the expected input field names (e.g. "invoice" or "amount") to verify the agent identified the read-only fields.

tests/tasks/uipath-human-in-the-loop/smoke_10_case_generic.yaml — verdict: Low

Issues:

• [Low] Meaningful coverage: no negative check confirming the agent did NOT recommend form fields or a schema block (which would indicate confusion with the QuickForm path). The file_contains check at line 58 only validates "task_title" key presence — any recommendation with that key passes regardless of whether the agent incorrectly included schema elements.

Suggested fixes:

• Add a file_contains criterion with excludes for "schema" or "formType" on recommendation.json to verify the agent correctly identified Generic as a no-schema path. Alternatively, add a run_command check: grep -L 'schema' recommendation.json (exit 0 means "schema" absent).

Within-PR duplicates

• [Low] Cluster: quality_12_case_path_selection.yaml, smoke_09_case_quickform.yaml — both test QuickForm path selection for Case surface. However, they operate at materially different depths: smoke_09 is pure pattern recognition (write recommendation, no artifact), quality_12 generates the actual caseplan.json artifact and validates its structure. This follows the established smoke-vs-integration layering pattern used by the existing Flow-surface tests in this skill. No action needed — flagged for awareness only.

Conclusion

⚠ 3 task(s) have issues, max severity High. Advisory only — not blocking merge.

The main action item is the answer leak in quality_12 (line 111 says "QuickForm" in a test designed to check if the agent picks the right path). The two smoke tests are solid for their tier — the Low-severity coverage gaps are minor polish items. The missing passing-run claim in the PR body is expected given the author's note that the JSON shape awaits runtime confirmation, but should be updated once confirmed.

---

[github-actions]

Claude finished @rohan-uip's task in 2m 53s —— View job

---

Coder-eval task lint (advisory)

3 task YAMLs changed; 0 Critical, 1 High, 0 Medium, 2 Low, 0 OK.

Rubric: .claude/commands/lint-task.md. This check is advisory and never blocks merge.

Evidence of passing run

❌ High — PR body does not claim the changed tasks have been run and passed. The body states "No automated test for Case QuickForm yet" and "Follow-up: add smoke_09_case_quickform.yaml once the JSON shape is confirmed by the runtime team". Please edit the PR description to add a line like: Ran skill-hitl-smoke-case-quickform locally and it passed.

Per-task lint

tests/tasks/uipath-human-in-the-loop/quality_12_case_path_selection.yaml — verdict: High

Issues:

• [High] Prompt over-specification: line 111 says The chosen path (QuickForm) does NOT need root-level bindings — the parenthetical (QuickForm) leaks the expected answer for a test whose stated purpose (lines 3–7) is to verify the agent reads the path-selection table and picks the right path. Any agent reading the constraints knows the answer without consulting the skill.
• [Low] Meaningful coverage: no criterion validates the assignee (data-enrichment-team) or priority (Medium) fields specified in the prompt at line 96. An agent could omit both and still pass all criteria.

Suggested fixes:

• Remove the parenthetical (QuickForm) from line 111. Rewrite as: "The correct path for this scenario does NOT need root-level bindings. Leave root.data.uipath.bindings as an empty array [] — do NOT add any entries with \"resource\": \"app\". The form schema lives inline in data.schema." This preserves the guardrail without leaking the answer.
• Add a file_contains check on caseplan.json for "data-enrichment-team" and "Medium" to validate assignee and priority were set.

tests/tasks/uipath-human-in-the-loop/smoke_09_case_quickform.yaml — verdict: Low

Issues:

• [Low] Meaningful coverage: no criterion validates the proposed input fields (invoice ID, total amount) appear in the recommendation's inputs array. An agent could emit "inputs": [] with the right case_path and outcomes and still pass.

Suggested fixes:

• Add a file_contains check on recommendation.json for one of the expected input field names (e.g. "invoice" or "amount") to verify the agent identified the read-only fields.

tests/tasks/uipath-human-in-the-loop/smoke_10_case_generic.yaml — verdict: Low

Issues:

• [Low] Meaningful coverage: no negative check confirming the agent did NOT recommend form fields or a schema block (which would indicate confusion with the QuickForm path). The file_contains check at line 58 only validates "task_title" key presence — any recommendation with that key passes regardless of whether the agent incorrectly included schema elements.

Suggested fixes:

• Add a file_contains criterion with excludes for "schema" or "formType" on recommendation.json to verify the agent correctly identified Generic as a no-schema path. Alternatively, add a run_command check: grep -L 'schema' recommendation.json (exit 0 means "schema" absent).

Within-PR duplicates

No duplicate clusters detected. smoke_09 and smoke_10 test different paths (QuickForm vs Generic); quality_12 and smoke_09 both exercise QuickForm but at different tiers (integration with artifact generation vs smoke with recommendation-only), following the established layering pattern.

Conclusion

⚠ 3 task(s) have issues, max severity High. Advisory only — not blocking merge.

The main action item is the answer leak in quality_12 (line 111 says "QuickForm" in a test designed to check if the agent picks the right path). The two smoke tests are solid for their tier — the Low-severity coverage gaps are minor polish items. The missing passing-run claim in the PR body is expected given the author's note that the JSON shape awaits runtime confirmation, but should be updated once confirmed.

---