uiplan 0.4.1

Lightweight UiPlan kit with MCP plan tools and scaffolding

UiPlan Light Kit

UiPlan is a spec-kit-style planning workflow for UiPath automation. It turns a rough idea into a reviewable, implementation-ready bundle of three files:

File	Answers	Contents
spec.md	What & why	scope, user stories, success criteria, constraints
plan.md	How	architecture, skill/tool routing, build & verification strategy
tasks.md	Execute	atomic checkbox tasks with per-task verify commands and evidence paths

This package installs the UiPlan helper files (templates, docs, skill wrappers) and a small MCP server that exposes uipath_plan_* tools to your AI client (Cursor, Claude, Copilot). You then drive the flow with /uiplan-* slash commands in chat.

It does not require cloning a repo, and it does not bundle the Studio review UI.

---

Prerequisite: UiPath skills CLI

The plan/implement flow routes through the official UiPath skills (uipath-planner, uipath-project-discovery-agent, and specialist skills), delivered by the @uipath/cli npm package. Install it once (needs Node.js):

npm install -g @uipath/cli
uip skills install --agent cursor   # fetch the UiPath skill catalog (refresh: uip skills update)

uiplan check reports whether node, npm, and uip are available; uiplan init warns if the UiPath CLI is missing. UiPlan grounding then discovers the installed skills dynamically (from .cursor/rules/ for Cursor or .claude/skills/ for Claude) and routes the generated plan only to skills that actually exist.

---

Quickstart (Cursor)

# 1. Scaffold UiPlan into the current repo and register the MCP server
uvx --from uiplan uiplan init --here --ai cursor

# 2. Confirm the toolchain is ready
uvx --from uiplan uiplan check

3. Reopen Cursor (or reload the window) so the new uiplan MCP server in .cursor/mcp.json is picked up.
4. In Cursor chat, run the staged commands (see below). Start with /uiplan-constitution once per repo, then ground → specify → plan → tasks → analyze → review → implement.

init only scaffolds files and wires the MCP server — it does not generate a plan. The planning happens through the slash commands.

---

The lifecycle (spec-kit parity)

Run these in your AI client's chat, in order. <slug> is the kebab-case bundle name derived from your spec title.

Command	Stage	What it does
/uiplan-constitution	guardrails	Establish project rules once per repo (read by every later stage).
/uiplan-ground <topic>	ground	Gather workspace context + discover available UiPath skills.
/uiplan-specify <title> --intent "<goal>"	specify	Create the bundle folder and spec.md. Alias: /uiplan-spec.
/uiplan-clarify <slug>	clarify	Resolve open [NEEDS CLARIFICATION] questions in the spec.
/uiplan-plan <slug>	plan	Generate plan.md (architecture, skill/tool routing, verify strategy).
/uiplan-tasks <slug>	tasks	Generate tasks.md from spec + plan + testing needs.
/uiplan-analyze <slug>	analyze	Read-only gate: spec↔plan↔tasks coverage, constitution conformance, and [skill:NAME] coverage vs the installed catalog.
/uiplan-review <slug> all	review	Run the structured review checks across all stages.
/uiplan-implement <slug>	implement	Execution handoff — runs the build loop against tasks.md (analyze first).

One-shot: /uiplan-full <title> chains ground → spec → plan → tasks for a fast draft.

constitution ─once─▶ ground ─▶ specify ─▶ clarify ─▶ plan ─▶ tasks ─▶ analyze ─▶ review ─▶ implement
                                                                         │           │
                                                                         └──gaps?─────┘ loop back, then re-run analyze

Worked example

/uiplan-constitution
/uiplan-ground "invoice exception handling"
/uiplan-specify "Invoice Exception Automation" --intent "Reduce manual triage time"
/uiplan-clarify invoice-exception-automation
/uiplan-plan invoice-exception-automation
/uiplan-tasks invoice-exception-automation
/uiplan-analyze invoice-exception-automation
/uiplan-review invoice-exception-automation all
/uiplan-implement invoice-exception-automation

Where files land

• Draft bundles: .cursor/plans/<slug>/spec.md|plan.md|tasks.md
• Accepted bundles are published to docs/plans/<slug>/
• Templates the generators use: templates/uiplan/
• Reference docs: docs/uiplan/ (see HOW_TO_USE.md and ANALYZE.md)

No PyPI login is needed to use the kit; tokens are only for publishing (see RELEASING.md).

---

Install options

# scaffold into the current repo (recommended)
uvx --from uiplan uiplan init --here --ai cursor

# target another directory
uvx --from uiplan uiplan init <path> --ai cursor

# pin a version
uvx --from uiplan==0.4.1 uiplan init --here --ai cursor

# pip / uv into an existing environment, then run directly
pip install uiplan
uiplan init --here --ai cursor

# from this repo (editable, for kit development)
uv run --project packages/uiplan-kit uiplan init --here --ai cursor --engine

init options

• --ai cursor|claude|copilot|all — which command/skill wrappers to scaffold (default cursor).
• --here — scaffold into the current directory (otherwise pass a PATH, default is cwd).
• --engine (default) / --static — --engine writes the uiplan MCP server into .cursor/mcp.json; --static scaffolds docs/templates only, no MCP wiring.
• --from-release <tag> — pull assets from a uiplan-kit-<tag>.zip GitHub release.
• --force — overwrite existing scaffolded files (otherwise existing files are kept).

---

Commands

• uiplan init [PATH] — scaffold helper files and (with --engine) register the MCP server.
• uiplan check — report uvx, MCP import, and node/npm/uip availability.
• uiplan version — print the installed kit version.
• uiplan-mcp — the stdio MCP server exposing the uipath_plan_* tools (launched by your AI client, not run by hand).

What gets installed

• templates/uiplan/
• docs/uiplan/
• docs/plans/constitution.md (seeded only if missing)
• .cursor/skills/uiplan*/SKILL.md (for Cursor mode)
• optional .claude/commands/ and .github/copilot/ wrappers (for claude/copilot/all)
• a uiplan entry in .cursor/mcp.json (with --engine)

---

Troubleshooting

• Slash commands don't appear / MCP tools missing — reopen Cursor (or reload the window) after init so .cursor/mcp.json is reloaded.
• analyze warns the skill catalog is empty — run uip skills install --agent cursor so referenced [skill:NAME] entries can be verified.
• uip not found — install Node.js, then npm install -g @uipath/cli.
• Re-running init didn't update files — init skips existing files; pass --force.

Uninstall

Delete the scaffolded files and remove the uiplan server entry from .cursor/mcp.json.

Releasing a new version

See RELEASING.md for the version bump, clean-room test, and publish steps.