# Set up OpenPlanr

Instructions for a coding agent (Claude Code, Codex or Cursor). The user pasted a line asking you to set up OpenPlanr in this repository. Work through the steps in order. Ask the user only where a step says to.

## 1. Check the tools

Run `node --version` and `git --version`.

OpenPlanr needs Node.js 20.19+, 22.13+ or 23.5+, and Git. If either is missing or too old, stop. Tell the user which one to install or upgrade, and don't continue.

## 2. Install the CLI

Ask once: "Install the OpenPlanr CLI with npm? (`npm install -g openplanr`)"

- **Yes:** run `npm install -g openplanr`, then `openplanr --version`.
- **No:** use `npx openplanr@latest` wherever these steps say `openplanr`.

## 3. Preview the setup

Run this from the repository root:

```bash
openplanr setup --runtime auto --scope user --skill-mode direct --dry-run
```

- `--runtime auto` picks the coding agents installed on this machine.
- `--skill-mode direct` installs Codex skills by their own names, so they run as `$spec`, `$ship` and so on.
- Cursor is installed per project, so this command skips it. For Cursor, also preview `openplanr setup --runtime cursor --scope project --dry-run`.

Show the user the preview: which agents it covers, where files go, and what it adds, updates or removes.

## 4. Apply it

Ask once: "Apply this setup?"

On yes, run the same commands with `--yes` in place of `--dry-run`. If the preview listed OpenPlanr files to remove, add `--replace-managed`. On no, stop and say nothing was changed.

## 5. Initialize the repository

```bash
openplanr init
```

This creates `.planr/`, where specs, stories and tasks live as files you review and version like code.

## 6. Verify

```bash
openplanr doctor
```

Report the result. If it shows a warning, show its suggested fix. Don't apply fixes without asking.

## 7. Start the first spec

Ask: "What is one feature you want to build next?"

Then tell the user to restart this agent, because new skills load on restart. Give them the exact command for after the restart, with their feature filled in:

| Agent | Command |
|---|---|
| Claude Code | `/spec "<their feature>"`, or `/planr:spec` if another plugin also has a `spec` skill |
| Codex | `$spec "<their feature>"`, choosing "OpenPlanr Spec" if another skill has the same name |
| Cursor | Mention the `planr-spec` rule in Composer, followed by the feature |

## Rules

- Write only inside this repository and the coding agent's own skill folders.
- Never ask for, read or store secrets. Skills and the openplanr CLI add no model calls or telemetry; the optional design engine calls OpenAI only if the user selects that provider and supplies their own key.
- If a command fails, show its exact error and stop. Don't guess a workaround.