Metadata-Version: 2.4
Name: uiplan
Version: 0.4.1
Summary: Lightweight UiPlan kit with MCP plan tools and scaffolding
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: typer>=0.15.1
Requires-Dist: rich>=13.9.4
Requires-Dist: httpx>=0.28.1

# 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](https://nodejs.org)):

```powershell
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)

```powershell
# 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.

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

### Worked example

```text
/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

```powershell
# 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`](RELEASING.md) for the version bump, clean-room test, and publish steps.
