feat(maestro-case): build missing agents and agentic processes inline during planning

[song-zhao-25]

Summary

Teaches the uipath-maestro-case skill to build a missing agent inline during Phase-1 planning instead of only leaving a placeholder. When an SDD-referenced agent can't be resolved at the Rule 17 empty-lookup gate, the skill offers a third option — Create the missing agent(s) inline — alongside force-pull and skip. On Create it builds each selected agent as an in-solution low-code sibling by spawning a sub-agent that invokes the uipath-agents skill (parallel, capped at 10), registers the siblings, and rediscovers + binds them via registry --local. Built agents enter Phase 2 as normal resolved tasks.

Agent-only first cut; the orchestration is written type-agnostically so other non-connector kinds can be enabled later.

⚠️ Depends on an unreleased CLI flag

This feature relies on uip maestro case registry <search|list|get> --local, which ships in CLI PR #2614 (still open). The published @uipath/cli does not yet have it. The skill probes for --local and gracefully degrades — when the flag is absent the Create option is suppressed and behavior is exactly as today. So this PR is safe to merge independently, but the feature only activates once a CLI with --local is released. Please don't expect the Create path to be exercisable in CI until then.

What changed (10 files, docs-only)

• SKILL.md — Rule 17 gains the agent-only Create option (constraint + redirect); the "never auto-invoke other skills / on-demand creation is future" anti-pattern is carved out for the agent path (non-agent kinds + uipath-planner keep no-auto-invoke); allowed-tools adds Agent (the sub-agent launcher).
• references/registry-discovery.md — 3-option gate + new § Create-on-Missing orchestration (capability probe → multi-select → parallel sub-agents --skip-solution-registration → sequential uip solution project add → resources refresh → rediscover/verify/bind).
• references/plugins/tasks/agent/planning.md — new § Creating an Agent inline: the typed-contract derivation, the self-contained build brief handed to uipath-agents, the failure contract.
• impl-json.md, placeholder-tasks.md, phased-execution.md, phase-0-interview.md, planning.md, bindings-v2-sync.md, case-commands.md — consistency edits + --local command docs.

Key design decisions

• Skill-driven build via sub-agent → uipath-agents (not a manual handoff): agent-build knowledge stays in uipath-agents; the case skill passes a pinned brief and verifies the result.
• Gate-selected only — SDD content alone never triggers a build (the SDD is untrusted sole input; the gate selection is the human-approval checkpoint).
• Binding reuses name+folder with the solution_folder sentinel (resourceKey="solution_folder.<name>"); the sibling ships inside the solution .uipx and co-deploys — never a separate tenant publish.
• Contract pins only the fields the case wires (typed Case Variable → type; unwired → the builder free-styles); type-vocabulary mapping is uipath-agents' concern.
• Rediscovery uses registry search "<name>" --local (matches by name); get --local matches only entityKey/project Id.

Verification

• Adversarial review across 4 dimensions (contradictions, completeness vs plan, skill-review rubric, CLI-fact accuracy). One critical defect caught and fixed: the verify step originally used get "<Name>" --local, which matches only entityKey — switched to search.
• allowed-tools token verified against the Claude Code docs: the sub-agent launcher is Agent (not Task, which is the unrelated task-list family) — corrected in e306645a.
• All relative links/anchors in the changed files resolve.

Runtime resolution — risk materialized and fixed (commit fb467d8)

The previously-documented open risk (runtime resolution of the solution_folder sentinel) materialized in a live end-to-end run and is now fixed.

• Symptom: deploy succeeded and the case became Active, but invoking it in Studio Web failed with folder not exist.
• Cause: the case task binding authored folderPath default = the solution_folder sentinel. Deploy correctly provisions the sibling into the real solution folder (resource refresh + debug_overwrites.json), but the deployed case package's runtime binding was never remapped — so the running case used the literal string solution_folder as the Orchestrator folder. CLI source confirms the case package's bindings[].default is passed through verbatim; validate accepts both solution_folder and "".
• Fix: the runtime folderPath binding default is now "" (empty = co-located; the case starts the sibling in its own deployed folder). The solution_folder sentinel stays ONLY in the resource-identity layer (resourceKey, resources/solution_folder/, bindings_v2.json key/value.folderPath) — they are intentionally decoupled for inline siblings, with a resourceKey carve-out so the <folderPath>.<name> formula doesn't collapse to .name. The over-stated "deploy verified" doc claims were corrected to deploy-provisions / runtime-needs-"". Applies to both the agent and agentic-process paths.
• Verified: the corrected binding was applied and invocation succeeds on alpha.uipath.com (2026-06-24).

Tests

Deferred — they need the released --local flag plus fixtures (a pre-seeded solution with a built sibling). Planned: a smoke (gate-offer), an integration (local-rediscovery), and an e2e (io-mismatch), grading artifacts rather than commands. Tracked as a follow-up once #2614 ships.

🤖 Generated with Claude Code

[github-actions]

Claude finished @song-zhao-25's task in 4m 2s —— View job

---

PR Review: feat(maestro-case): build missing agents inline during planning

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

---

Summary

Adds a third option ("Create the missing agent(s) inline") to the Rule 17 empty-lookup gate in uipath-maestro-case. When an SDD-referenced agent can't be resolved, the skill now offers to build it as an in-solution low-code sibling by spawning a sub-agent that invokes uipath-agents, then registers and binds it via registry --local. The feature is gated behind a CLI capability probe (--local flag) and degrades gracefully when absent. Well-structured 10-file docs-only change across SKILL.md, 8 reference files, and 1 plugin planning file.

Change-by-Change Review

1. skills/uipath-maestro-case/SKILL.md (+4/-3)

Severity: OK

Three targeted changes: allowed-tools gains Agent (verified correct per Claude Code docs — Agent is the sub-agent launcher, not Task). Rule 17 is expanded with the Create option + agent-only constraint + --local suppression. The anti-pattern carve-out for agent inline-create is cleanly scoped — non-agent kinds and uipath-planner keep the no-auto-invoke rule. Phase 1 bullet adds a one-sentence bridge linking to the authoritative registry-discovery.md § Create-on-Missing. Frontmatter unchanged (name matches, description under 1024 chars).

2. skills/uipath-maestro-case/references/registry-discovery.md (+57/-9)

Severity: OK

This is the authoritative home for the cross-cutting orchestration. The new § Create-on-Missing build and rediscovery (§0–4 + Reject case) is well-structured: capability probe (§0), multi-select (§1), parallel build with cap (§2), sequential registration (§3), rediscover/verify/bind (§4), and reject case. The gate prompt shape is updated cleanly — option labels are tighter (Force pull and re-resolve instead of Yes, force pull and re-resolve). The search vs get distinction for --local is correctly documented throughout (lines 98, 101, 104). The --local semantics paragraph (PascalCase keys, shape differences between search/get/list) is detailed and useful.

One small note: §3 references [implementation.md](implementation.md) § Step 6.0b — the file exists and the cross-reference is valid.

3. skills/uipath-maestro-case/references/plugins/tasks/agent/planning.md (+50/-1)

Severity: OK

The new § Creating an Agent inline section covers the agent-specific parts: I/O contract computation (Step 1), builder brief template (Step 2), binding shape (Step 3), and failure contract. The layering is clean — the cross-cutting orchestration delegates here for agent-specific content, and this file links back to registry-discovery.md § Create-on-Missing for the orchestration. The pinned I/O contract logic (wired-to-typed-var → type pinned, wired-but-type-unknown → name only, unwired → omit) is well-specified. The builder brief template is self-contained. The v1 low-code only caveat and runtime solution_folder caveat are honest.

The folder-path field table update (line 15) adds the solution_folder sentinel with a link — bridge-level, clean.

4. skills/uipath-maestro-case/references/placeholder-tasks.md (+23/-2)

Severity: OK

Adds three pieces: (1) a bridge callout at the top of § Upgrade Procedure clarifying built-inline agents skip the upgrade procedure; (2) the completion-report shape for inline-built agents (separate from placeholder listing); (3) three new anti-patterns. All bridge-level — detail defers to registry-discovery.md § Create-on-Missing. The search vs get distinction is correctly noted in §2.

5. skills/uipath-maestro-case/references/case-commands.md (+8/-0)

Severity: OK

Documents the --local flag for list/search/get with examples, option table entry, and a --local semantics paragraph covering key shapes. The get --local caveat (matches only entityKey/project Id, never display name) is clearly called out — consistent with the search vs get guidance elsewhere.

6. skills/uipath-maestro-case/references/phased-execution.md (+4/-1)

Severity: OK

Adds a row to the Phase 2 task-shape table for agent built inline (not a placeholder, fully resolved). Adds a bridge callout in the placeholder section. Updates completion report §4 to mention inline-built agents. All bridge-level with links to authoritative docs.

7. skills/uipath-maestro-case/references/planning.md (+4/-0)

Severity: Low

Two callouts added: (1) after the task-type catalog noting agent-only create-on-missing (bridge + link, line 99); (2) in §3.4 "Missing agent — offer to create first" (line 126). The §3.4 callout summarizes the orchestration flow in ~2 sentences ("spawns a sub-agent that invokes uipath-agents, then rediscovers + binds via registry --local") before linking. This is borderline per reference pointer discipline — the summary is slightly more than pure bridge, but it's needed to explain why the agent doesn't immediately fall through to the unresolved steps below. Acceptable.

8. skills/uipath-maestro-case/references/plugins/tasks/agent/impl-json.md (+3/-1)

Severity: OK

Adds a callout at Step 0 clarifying that built-inline siblings skip tasks describe (their I/O was already read via search --local during planning). Adds folderPath default for the solution_folder sentinel at Step 1. Both are agent-specific binding guidance — not duplication.

9. skills/uipath-maestro-case/references/bindings-v2-sync.md (+2/-0)

Severity: OK

Single callout explaining the solution_folder.<name> binding as the author-side counterpart mapped by resource refresh → debug_overwrites.json. Correctly notes the CLI writes that file, not the skill.

10. skills/uipath-maestro-case/references/phase-0-interview.md (+2/-2)

Severity: OK

Two edits: (1) the Placeholder — resolve later option now notes that Phase 1's Rule 17 gate additionally offers inline create for agents; (2) the empty-match batch prompt adds the Create option. Both are bridge-level annotations linking to registry-discovery.md § Create-on-Missing.

What's Missing

• Tests — No new test tasks cover the Create-on-Missing feature. The PR body explicitly acknowledges this and explains the dependency on unreleased CLI --local flag (PR #2614). Existing tests in tests/tasks/uipath-maestro-case/ cover other flows but not this one. Medium — tracked as follow-up, acceptable given CLI dependency.
• Nothing else identified. CODEOWNERS is present. All relative links resolve. No secrets, no binary files, no cross-skill file references. Changes are scoped to uipath-maestro-case only.

Area Ratings

Area	Status	Notes
Frontmatter	OK	name matches, description under 1024 chars, allowed-tools correctly adds Agent
E2E Tests	Medium	Deferred — blocked on unreleased --local CLI flag; explicitly documented
Skill Body	OK	Rule 17 updated cleanly, anti-pattern carve-out well-scoped, Phase 1 bullet is bridge-level
References & Assets	OK	Authoritative content in registry-discovery.md + agent/planning.md; other files use bridge references. Minor verbosity in planning.md §3.4 callout (Low)
Repo Hygiene	OK	CODEOWNERS present, no secrets, scoped changes, skill-status.json entry exists

Issues for Manual Review

• --local flag accuracy. The PR documents --local semantics (PascalCase keys, search vs get matching behavior, solution discovery walk) based on an unreleased CLI (PR #2614). These claims can't be verified against the published CLI. Once the flag ships, the documented shapes should be spot-checked.
• solution_folder runtime resolution. The PR honestly notes this is "not yet end-to-end verified on a tenant" — validate accepts it structurally but deploy-time behavior is unproven. Worth tracking.
• Sub-agent behavior. The builder brief template instructs uipath-agents to build non-interactively with --skip-solution-registration and return structured JSON. Whether the agents skill reliably follows this contract when invoked as a sub-agent is a runtime concern not testable from docs alone.

Conclusion

Clean, well-structured PR. The architectural layering is sound: cross-cutting orchestration in registry-discovery.md, agent-specific contract/brief/binding in agent/planning.md, bridge references everywhere else. The capability probe + graceful degradation design means the feature is safe to merge independently of the unreleased CLI flag. The main gap is test coverage, which is acknowledged and blocked on external dependencies. Approve — no blocking issues.