# epic-harness Cursor Integration — Install Guide

**CRITICAL**: Run `HARNESS_DIR=$(epic-harness path)` first. NEVER use `.harness/` in the project directory.

## Requirements

- **Cursor 1.7 or later** — hooks (`preToolUse`, `postToolUse`, `sessionEnd`) and custom slash commands require Cursor 1.7+
- **epic-harness binary** in `PATH`

---

## 1. Install the epic-harness Binary

**Homebrew (macOS/Linux):**
```bash
brew install epicsagas/tap/epic-harness
```

**Cargo (from source):**
```bash
cargo install epic-harness
```

Verify the install:
```bash
epic-harness --version
```

---

## 2. Install Hooks

Hooks tell Cursor to run epic-harness automatically on tool events.

**Project-level** (affects only this project):
```bash
cp integrations/cursor/hooks.json .cursor/hooks.json
```

**Global** (affects all Cursor projects):
```bash
cp integrations/cursor/hooks.json ~/.cursor/hooks.json
```

The `hooks.json` file follows [Cursor’s hooks schema](https://cursor.com/docs/hooks): **`version` must be `1`**, hook names are **camelCase** (`preToolUse`, not `PreToolUse`). The shell tool is matched with **`Shell`** (not `Bash`). If any of these are wrong, Cursor may ignore the file.

The hooks wire up:
- `preToolUse` on `Shell` → `epic-harness guard` (blocks dangerous commands)
- `postToolUse` on `Edit` / `Write` → `epic-harness polish` (auto-format + type-check)
- `postToolUse` on `*` → `epic-harness observe` (async observation recording)
- `sessionEnd` → `epic-harness reflect` (evolution loop)

---

## 3. Install Rules

Rules provide always-on context that loads harness state at session start and applies quality skills automatically.

```bash
mkdir -p .cursor/rules
cp integrations/cursor/rules/harness-context.mdc .cursor/rules/
```

These rules replace the `session-start` hook (which Cursor does not expose) by injecting harness context into every session automatically.

<!-- Coming in a future release:
```bash
cp integrations/cursor/rules/harness-skills.mdc .cursor/rules/
```
Condensed TDD, secure, verify, simplify, and perf rules will be available as a separate `harness-skills.mdc` rule file in a future release.
-->

---

## 4. Install Slash Commands

Custom slash commands expose the three top-level epic-harness commands inside Cursor’s Composer.

Each command file uses YAML frontmatter with **`name`** (kebab-case identifier, same as the file stem) and **`description`** (one-line summary). [Cursor’s command format](https://cursor.com/docs/reference/plugins) expects both; if `name` is missing, the slash menu may show only `(user)` instead of your description.

```bash
mkdir -p .cursor/commands
cp integrations/cursor/commands/*.md .cursor/commands/
```

After installation, the following commands are available in Cursor Composer:
- `/orbit` — Autonomous spec→ship pipeline
- `/evolve` — Manage skill evolution
- `/team` — Design a project-specific agent team

The remaining workflow steps (spec, go, check, ship, discover) are **auto-triggered skills** — they activate based on context signals without manual invocation.

---

## 5. Install Agents (Future)

> **Note:** Agent knowledge is now embedded within skills (builder, reviewer, auditor, planner modes). No standalone agent files are needed. Use the built-in agent capabilities in Cursor's Composer.

---

## Install command behavior

`epic-harness install cursor` (and `--local`) **writes or updates** every embedded integration file (`hooks.json`, `rules/`, `commands/`, `agents/`) so it matches the binary. Files that already match are left unchanged. This fixes the case where an older or empty `hooks.json` existed and would previously have been skipped entirely.

## 6. Verify Installation

```bash
ls .cursor/hooks.json .cursor/rules/ .cursor/commands/
```

Start a new Cursor session. The Composer should load harness context from `$HARNESS_DIR/memory/` and report any evolved skills from `$HARNESS_DIR/evolved/`.

---

## File Layout After Install

```
.cursor/
├── hooks.json          # Hook event → epic-harness subcommand mapping
├── rules/
│   └── harness-context.mdc   # Session start context + auto-behaviors
├── commands/
│   ├── orbit.md
│   ├── evolve.md
│   └── team.md
└── (skills auto-trigger based on context — no manual files needed)
```

---

## Troubleshooting

**"epic-harness not found" in hook output**
The hooks degrade gracefully — they print a warning and continue. Install the binary and ensure it is in your shell's `PATH`. Restart Cursor after installing.

**Hooks not firing**
Confirm Cursor version is 1.7 or later. Check `Cursor > Settings > Hooks` to verify hooks are enabled for the project. Open `hooks.json` and confirm it has `"version": 1` and camelCase keys (`preToolUse`, `postToolUse`, `sessionEnd`). Re-run `epic-harness install cursor` after upgrading epic-harness so the file matches the embedded copy.

**Agents not listed**
Agents are not yet available for the Cursor integration. They will be added in a future release. Use the built-in agent capabilities in the meantime.

**Rules not loading**
Confirm `.mdc` files are in `.cursor/rules/` (not a subdirectory). Restart Cursor to pick up new rule files.

**Commands not appearing**
Confirm `.md` files are in `.cursor/commands/`. In Composer, type `/` to see available custom commands.

---

## Memory Integration

epic-harness includes a unified memory store shared across all agents and tools.

**Session start — inject relevant context:**
```bash
epic-harness mem context --project <slug>
```
This is surfaced automatically at session start via the `harness-context.mdc` rule.

**Manual add — record a decision or pattern:**
```bash
epic-harness mem add --title "Chose Postgres over SQLite" --type decision --body "SQLite lacks concurrent writes needed for our workload."
```

**Supported `--type` values:** `decision`, `pattern`, `note`, `architecture`

**Web UI — browse and search all memory:**
```bash
epic-harness mem serve
# → http://localhost:7700
```

**Auto-record via hook:** The `postToolUse` hook runs `epic-harness mem-observe` after every Edit/Write tool call. If the tool output or assistant message contains decision keywords (`decision`, `architecture`, `pattern`, `chose`, `decided`, `approach`), the entry is recorded automatically.

**Shorthand via `harness` symlink** (if `hooks/bin/harness → epic-harness` exists):
```bash
harness mem add --title "..." --type decision --body "..."
harness mem context --project <slug>
harness mem serve
```
The symlink is created automatically by `epic-harness install`. Run `epic-harness install --check` to verify.
