# Priority Forge — Cursor Plugin

A Cursor plugin that makes Priority Forge a first-class citizen in every Cursor session: MCP server entry, always-applied rule, proactive session-start task surfacing, and an autostart hook that brings the backend up if it's down.

## What this plugin bundles

| File                                    | Purpose                                                                                                                                                                                  |
|-----------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `plugin.json`                           | Plugin manifest.                                                                                                                                                                         |
| `mcp.json`                              | Registers the `priority-forge` MCP server at `http://127.0.0.1:3456/mcp`.                                                                                                                |
| `rules/priority-forge.mdc`              | Always-applied rule: Cursor agents route all task tracking through Priority Forge and never use competing PM MCPs (Linear, Jira, etc.) in a session where this plugin is enabled.        |
| `hooks/hooks.json` + `hooks/sessionStart.sh` | `sessionStart` hook that checks the backend and, if it's down, tries to kick the persistent service or (as a fallback) nohup-starts the backend from the Priority Forge repo.       |
| `skills/capture-task/SKILL.md`          | Directs agents to call `mcp_priority-forge_create_task` whenever the user describes work.                                                                                                |
| `skills/check-priorities/SKILL.md`      | Directs agents to fetch the top priority at session start and log a context switch if the user's request diverges from it.                                                               |

## Prerequisites

The plugin does **not** install the Priority Forge backend. You still need a working Priority Forge installation somewhere on this machine:

```bash
git clone https://github.com/Unobtainiumrock/priority-forge.git
cd priority-forge
bash setup.sh                     # installs backend + persistent service (default-on)
```

`setup.sh` writes a repo-path discovery file (`~/.local/share/priority-forge/repo-path` on Linux, `~/Library/Application Support/priority-forge/repo-path` on macOS) that this plugin's `sessionStart.sh` reads at runtime so it can find your checkout regardless of where Cursor launches from.

## Install options

### Option A: via the Priority Forge setup script (recommended)

```bash
cd path/to/priority-forge
./setup.sh install-cursor-plugin
```

This copies `cursor-plugin/` to `~/.cursor/plugins/priority-forge/` and refreshes the repo-path discovery file. Then open Cursor's plugin settings, enable `priority-forge`, and restart Cursor.

### Option B: manual copy

```bash
cp -R cursor-plugin ~/.cursor/plugins/priority-forge
chmod +x ~/.cursor/plugins/priority-forge/hooks/sessionStart.sh
```

Then write the discovery file yourself so the hook can locate setup.sh:

```bash
# Linux
mkdir -p ~/.local/share/priority-forge
echo "$PWD" > ~/.local/share/priority-forge/repo-path

# macOS
mkdir -p "$HOME/Library/Application Support/priority-forge"
echo "$PWD" > "$HOME/Library/Application Support/priority-forge/repo-path"
```

Enable the plugin in Cursor and restart.

## Verifying

From your Priority Forge checkout:

```bash
npm run verify --cursor
```

Expected passing checks:

- `Cursor MCP config`: `~/.cursor/mcp.json` has `priority-forge`.
- `Cursor rule`: `~/.cursor/rules/priority-forge.mdc` exists with `alwaysApply: true`.
- `Cursor sessionStart hook`: hook script is registered in `~/.cursor/hooks/hooks.json` and executable.

(If you installed via the plugin only — not via `setup.sh` — the installer-written rule file under `~/.cursor/rules/` will not exist; the plugin-bundled rule at `~/.cursor/plugins/priority-forge/rules/priority-forge.mdc` still applies as long as the plugin is enabled.)

## Relationship to the installer path

`./setup.sh install` writes to the same three spots as this plugin (`~/.cursor/mcp.json`, `~/.cursor/rules/priority-forge.mdc`, `~/.cursor/hooks/`) directly — no plugin required. The plugin is the redistributable path: install Priority Forge on a new machine, copy the plugin, done. The installer-written files and the plugin-bundled files are compatible: if both exist, the plugin's entries take precedence for plugin-scoped hooks and rules while the user-global MCP entry continues to work either way.

## Uninstalling

```bash
rm -rf ~/.cursor/plugins/priority-forge
```

If you also want to remove the installer-written entries:

- `~/.cursor/mcp.json` — remove the `priority-forge` key under `mcpServers`.
- `~/.cursor/rules/priority-forge.mdc` — delete.
- `~/.cursor/hooks/hooks.json` — remove the `priority-forge` entry under `sessionStart`.
- `~/.cursor/hooks/priority-forge/` — delete.
