feat(case-skill): document CLI mutation commands + hitl add opt-in

[dushyant-uipath]

Summary

• case-commands.md: Revised intro, added Case Plan Mutation Commands section documenting cases add/get/edit, stages add/edit/get/remove, tasks add/edit/get/remove/enrich/add-connector, and hitl add (CLI PR #1207).
• action/impl-json.md: Added CLI opt-in callout pointing to uip maestro case hitl add.

Motivation

Demo scripts (Health Claims, Commercial Lending, Mortgage Loan Origination) build case plans via CLI. Without these commands in the skill reference, coding agents default to direct JSON writes only.

Notes

hitl add is gated on CLI PR #1207 merging. All other mutation commands are already shipped.

CODEOWNERS: @baishalighosh @dushyant-uipath @maestro-cli-team

[github-actions]

PR Review: feat(case-skill): document CLI mutation commands + hitl add opt-in

• Read review criteria and project conventions
• Read full diff and existing PR comments
• Read full changed files for context
• Run skill-specific checks (links, cross-refs, CODEOWNERS, secrets)
• Post review findings

---

Summary

Adds a new "Case Plan Mutation Commands" section to case-commands.md documenting 13 CLI subcommands (cases add/get/edit, stages add/edit/get/remove, tasks add/edit/get/remove/enrich/add-connector, hitl add). Also adds a CLI opt-in callout to impl-json.md pointing agents to hitl add as an alternative to direct JSON writes. Well-structured, consistent with existing command documentation, and properly scoped.

Change-by-Change Review

1. skills/uipath-maestro-case/references/case-commands.md

Severity: Medium

The new section is well-organized, with consistent flag tables, output shapes, and examples. Several issues:

a. Positional argument placeholder inconsistency (case-commands.md:267)
hitl add documents the positional stage argument as <stageId> (camelCase), while every other command in the file uses <stage-id> (kebab-case). Per repo convention, placeholders use <UPPER_SNAKE_CASE> in angle brackets.

• Line 267: <stageId> → should be <stage-id> (to match lines 113, 155, 186, 209) or <STAGE_ID> (to match repo convention).
• Fix this →

b. Priority value inconsistency between hitl add and tasks add --type action (case-commands.md:169 vs case-commands.md:269)

• tasks add documents priority as Low, Medium, High, or Critical (default: Medium)
• hitl add documents priority as Low, Medium, or High (default: Low) — no Critical, different default
• impl-json.md:39 also lists Critical as valid for the JSON field

If this difference is intentional (CLI hitl add doesn't support Critical), add a brief note explaining why. If unintentional, align them.

c. Removed context paragraph (diff line 1–4)
The original file opened with a paragraph explaining that caseplan.json mutations are direct file edits. The replacement intro is clearer and better structured, but the original also stated "The commands below are the only uip invocations the skill issues" — a useful boundary statement for agents. The new intro doesn't have an equivalent constraint. Consider whether agents need that guardrail.

d. Missing --output json in mutation command examples
Per repo convention (CLAUDE.md: "CLI commands must use --output json when output is parsed programmatically"), examples like cases add, stages add, hitl add omit --output json. The global options section documents it, but agents copy-paste examples directly. Consider adding --output json to at least the first example of each command group.

e. stages edit and stages get missing Output shape (case-commands.md:105-130)
Most commands document their output JSON shape (e.g., StageAdded, StageRemoved, TaskAdded). stages edit and stages get don't — agents won't know what to parse from the response.

2. skills/uipath-maestro-case/references/plugins/tasks/action/impl-json.md

Severity: OK

The CLI opt-in callout is well-placed and concise. The relative link ../../../case-commands.md#uip-maestro-case-hitl-add resolves correctly. The callout follows reference-pointer discipline — bridge content only, no duplication of the hitl add documentation. Clean.

What's Missing

• No test task for CLI mutation commands. Existing tests (init_validate.yaml, registry_discovery.yaml) cover scaffolding and registry discovery but not the new mutation workflow (cases add → stages add → tasks add). Since this PR substantially changes the skill by adding CLI mutation paths, a test covering the CLI-based plan building would strengthen confidence. (Medium — most skills are not yet test-compliant, and mutation commands may need a mock CLI to test.)
• CODEOWNERS mismatch. PR description lists @baishalighosh @dushyant-uipath @maestro-cli-team but the existing CODEOWNERS entry (line 48) shows @charlesliu9 @song-zhao-25 @jundayin. If the PR author intends to add new owners, CODEOWNERS should be updated in this PR.
• No error handling guidance. The mutation commands document the success output shape but don't specify what happens on failure (e.g., adding a stage to a non-existent file, duplicate stage IDs, invalid task type). Agents need to know what to check and how to recover.

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	Issue	No test task covers the new CLI mutation workflow
Skill Body	OK	No SKILL.md changes
References & Assets	Issue	Placeholder inconsistency, missing output shapes, priority value mismatch
Repo Hygiene	OK	No secrets, no cross-skill refs, all links resolve, changes scoped to skill

Issues for Manual Review

• CLI hitl add availability: Documented as gated on PR #1207. Verify the flag set and output shape match the actual implementation once that PR ships.
• Priority enum difference: Confirm whether hitl add intentionally omits Critical and defaults to Low (vs tasks add --type action which includes Critical and defaults to Medium).
• hitl add vs tasks add --type action overlap: Both commands can create action tasks. The skill should clarify when an agent should use hitl add vs tasks add --type action — currently there's no guidance on disambiguation.

Conclusion

Good addition that fills a real documentation gap for CLI-based case plan construction. The structure and writing quality are strong. Requesting changes for: (1) the <stageId> placeholder inconsistency — straightforward fix, and (2) clarification on the hitl add vs tasks add --type action priority/scope differences. The missing output shapes and --output json in examples are lower priority but would improve agent reliability.

View job run