# Wolbarg Coordination for Cursor

Cursor plugin that turns Wolbarg’s coordination-plane design into something agents can use natively: **MCP tools + skill + rules + hooks**.

**Status:** `@wolbarg/cursor@0.2.0` — production-ready for Cursor workspaces that complete `wolbarg init` and (for hard guarantees) enable `fail_closed_protected_paths`. Verify with MCP tool `production_readiness` (`ready: true`).

## Hard requirement: `wolbarg init`

```bash
npx wolbarg init
```

That writes `.wolbarg/config.json`. Without it:

- MCP starts in **setup mode** (tools return `WOLBARG_NOT_INITIALIZED` instead of crashing)
- Hooks deny / warn until init exists
- `CoordinationPlane` throws under default options

After init, reload MCP / reopen the agent chat.

This is **not** another coding agent and **not** an orchestrator. Cursor remains the runtime.

See the RFC: [cursor coordination plane](https://github.com/wolbarg/wolbarg/blob/main/docs/rfcs/0001-cursor-coordination-plane.md).

## Production checklist

| Gate | How to verify |
| --- | --- |
| Init | `.wolbarg/config.json` exists |
| Mechanics | `coordination_scorecard` → ≥ 9.5 |
| Fail-closed | Copy [`examples/coordination.production.json`](./examples/coordination.production.json) → `.wolbarg/coordination.json` |
| Compliance audit | Hooks/MCP `check_path_write` write `compliance_events`; see `compliance_report` |
| Actor identity | Set `WOLBARG_ACTOR_ID` or `.wolbarg/actor.id` so hooks ignore your own leases |
| Hard gate | MCP `production_readiness` → `ready: true` |

### Recommended production policy

```json
{
  "enforcement": "fail_closed_protected_paths",
  "protectedGlobs": ["src/auth/**", "src/payments/**", "src/billing/**"],
  "defaultClaimTtlSeconds": 1800,
  "allowClaimBreakBy": "human",
  "pulseTtlSeconds": 900
}
```

Default remains **advisory** for gentle onboarding; production deployments should switch to fail-closed on protected globs.

## What you get

| Piece | Role |
| --- | --- |
| MCP server | Agent API (`workspace_briefing`, `claim_scope`, …) |
| Skill | When/how agents should coordinate |
| Rule | Always-on short contract |
| Hooks | Session briefing + claim checks on writes (deny when fail-closed) |
| SQLite store | `.wolbarg/coordination.db` + compliance audit log |
| Scorecard / prod gate | CI-friendly `coordination_scorecard` + `production_readiness` |

## Install

```bash
git clone https://github.com/wolbarg/cursor.git
cd cursor
npm install
npm run build
npm test
```

In the target workspace:

```bash
npx wolbarg init
```

### Option A — project MCP (prefer absolute paths on Windows)

```json
{
  "mcpServers": {
    "wolbarg-cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@wolbarg/cursor"],
      "env": {
        "WOLBARG_WORKSPACE_ROOT": "C:/absolute/path/to/workspace"
      }
    }
  }
}
```

### Option B — Cursor plugin (local symlink)

```bash
# macOS / Linux
mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)" ~/.cursor/plugins/local/wolbarg-cursor-mcp
```

### Option C — npm bin

```bash
npx -y @wolbarg/cursor
```

## Agent workflow

1. `workspace_briefing` — use short queries; pass `wait_ms` when siblings may still be writing  
2. `claim_scope` — lease paths before contested edits  
3. `record_finding` — facts / decisions / dead_ends (+ tags)  
4. `pulse_update` / `heartbeat_claim`  
5. `release_claim` + `create_handoff`  
6. `compliance_report` / `production_readiness` — ops

## MCP tools

- `workspace_briefing` (supports `wait_ms`, `min_*`)
- `claim_scope` / `heartbeat_claim` / `release_claim`
- `record_finding` / `search_findings`
- `upsert_work_item` / `list_work_items`
- `create_handoff` / `pulse_update`
- `coordination_status` / `coordination_scorecard`
- `compliance_report` / `production_readiness`
- `check_path_write`

## Library API

```ts
import { CoordinationPlane } from "@wolbarg/cursor";

const plane = new CoordinationPlane({ rootPath: process.cwd() });
const gate = plane.productionReadiness();
if (!gate.ready) throw new Error(gate.blockers.join("\n"));
plane.close();
```

## Design notes

- **Init is mandatory** for full plane operation.
- **Git remains code SoR** — the DB is coordination + compliance truth only.
- **Claims use TTL + heartbeat** — crashed agents expire.
- Findings use local FTS (+ synonym expansion); core Wolbarg semantic memory uses project embedding config separately.
- Conflicts are flat JSON for MCP clients.
- Requires **Node.js ≥ 22.5** (`node:sqlite`, WAL + busy_timeout).

## Development

```bash
npm run build
npm test
npm run mcp
```