Cursor Integration

July 19, 2026 · View on GitHub

Last updated: 2026-07-19

Scope: PM handoff integration and supported Cursor adapter route. Adapter evidence, bootstrap route, and promotion gates live in docs/research/cursor-adapter-candidate.md and .cursor/AGENTS.md.

Goal

Use Cursor as the PM side and Claude Code Harness as the implementation side without losing task ownership or verification discipline.

When the operator wants to stay inside Cursor for Harness workflows, use the adapter route under .cursor-plugin/ and .cursor/AGENTS.md. Cursor is supported after live H4 (2026-07-17) and H7 release-preflight fail-closed (2026-07-19), with harness-side containment (below).

Containment disclosure

Cursor adapter support is supported, but containment is harness-side, not Cursor-native sandboxing.

(a) No traditional sandbox: cursor-agent has no filesystem jail comparable to Codex --sandbox. File edits are not confined by --sandbox and can write outside the workspace.

(b) Allowlists are best-effort: Cursor permission allowlists are convenience controls, not a security boundary (per Cursor's own documentation).

(c) Harness-side containment is the effective boundary: dedicated .git worktree isolation, Lead diff review, cherry-pick through R01–R13 policy engine, plus .cursorignore for secret reads.

(d) No bypass modes: --force / "Run Everything" is never used in Harness Cursor workflows.

See also docs/known-limitations.md.

Role Split

  • Cursor: planning, review sign-off, release judgment (handoff mode)
  • Claude Code Harness: implementation, local verification, handoff back to PM

This split works best when both sides share the same repository, branch, and Plans.md.

1. Plan in Cursor

Use the Cursor-side command templates to create or refine Plans.md:

  • templates/cursor/commands/start-session.md
  • templates/cursor/commands/plan-with-cc.md
  • templates/cursor/commands/handoff-to-claude.md
  • templates/cursor/commands/review-cc-work.md

Adapter route (same repo, supported tier with harness-side containment):

  • Read .cursor/AGENTS.md for plan/work/review routing guidance
  • Invoke harness-plan, harness-work, or harness-review skills when available

2. Implement in Claude Code

Inside Claude Code, run the Harness loop:

/harness-setup
/harness-plan
/harness-work
/harness-review

Use /harness-work all only after the plan is approved and only if you are comfortable with the evidence-pack contract described in docs/evidence/work-all.md.

3. Handoff Back to Cursor

For a PM-style return path, use:

/handoff-to-cursor

If you prefer the unified release path, /harness-release handoff can also be used when the implementation and review loop is complete.

Plans.md Markers

The safest shared contract is:

  • pm:依頼中 / cc:TODO
  • cc:WIP
  • cc:完了
  • pm:確認済

Cursor should own PM markers. Claude Code should own worker markers.

Guardrails

  • Do not let Cursor and Claude Code edit the same task block at the same time.
  • Keep one source of truth for acceptance criteria: Plans.md.
  • Treat production deployment judgment as the PM side's responsibility.
  • If the worker side fails the same issue three times, stop and escalate instead of widening fallback logic.
  • Do not claim Claude-identical FS jail or full-tool PreToolUse parity for Cursor.

Minimum Sanity Check

Before starting a shared session, confirm:

  1. Both tools point at the same git branch.
  2. Both tools can see the same Plans.md.
  3. The implementation request includes acceptance criteria and expected verification commands.
  4. The PM side knows whether release is in or out of scope.
  5. Support wording treats Cursor as supported with harness-side containment only.

Adapter Verification

Static contract (required):

bash tests/test-cursor-adapter-candidate.sh

This verifies manifest shape, AGENTS bootstrap routing, and supported-tier wording with containment caveats. It does not prove full Breezing multitask parity.