Skip to content

Cursor Overlay Validation

Jump to bottom
Priscila Saboia Moreira edited this page Jun 30, 2026 · 2 revisions

type: analysis up: "Agent-Overlays" extends: "Agent-Overlays" derived_from:

Cursor Overlay Validation

First live validation of the Cursor overlay on a real GitHub-hosted adopting project, 2026-06-30. Closes the validation gap previously flagged in the template's README ("Cursor overlay is shipped but unvalidated in a live session.") with empirical evidence: four behavioural tests pass with two non-blocking observations nameable. Filed in response to a real-world question about whether collaborators using Cursor and Claude Code can share the same wiki memory on the same project.

Filing meta-note. This page uses type: analysis, which is not in the current SCHEMA's declared type list (PR #29 adds the type; pending). Same approach as Analysis-of-Wiki-Push-Race-Pattern and Analysis-of-model_fusion-Recommendations; both become retroactively valid once PR #29 lands.

Question

Does the Cursor overlay produce the same wiki-memory experience as the Claude Code overlay end-to-end on a real adopting project, when installed alongside the Claude Code overlay on the same host?

The README's Status section flagged: "Only the Claude Code path has been validated end-to-end. The Cursor overlay [...] is shipped but unvalidated in a live session." The validation gap had been open since the template shipped, despite the Cursor overlay's design being symmetric with Claude Code's.

Context

The test ran against a real GitHub-hosted host (anonymized here; identifiable to project maintainers) that had already adopted via adopt --apply --agent=claude-code. The Cursor overlay was installed on top, alongside the existing Claude Code overlay, since the template explicitly supports both overlays coexisting (instantiate.sh --agent=all is a first-class option).

Adopt's parser still refuses --agent=cursor (see issue #65), so the install was a manual workaround: fresh clone of template main, copy .cursor/rules/*.mdc with {{REPO_NAME}} substituted, copy wiki/agents/cursor/, run bash wiki/agents/cursor/setup.sh. The setup script was idempotent on the host's CLAUDE.md — claude-code had injected the lw:memory-boundary and lw:wiki-maintenance sentinels at adopt time; cursor's setup detected presence and skipped re-injection (the two overlays share the same sentinel names by design).

Cursor was opened on the host. The agent reported which rules it loaded: wiki-as-memory.mdc and CLAUDE.md as always-applied; wiki-experiment.mdc, wiki-source.mdc, wiki-lint.mdc as agent-requestable. Four behavioural prompts followed.

Analysis

Test 1 — Proactive read of SCHEMA

Prompt: "What does SCHEMA say about page types I can use?"

Cursor opened SCHEMA_<repo>.md on disk and returned the actual page-type table verbatim — concrete types (concept, entity, source-summary, synthesis, analysis, decision, index, comparison, reference, untyped) with the required-structure constraints for analysis and decision. No invention. The wiki-as-memory.mdc rule's "read the wiki for context" behaviour produced proactive reading on demand. ✅

Test 2 — Link discipline applied without explicit reminder

Prompt: "What's the state of develop and the last merged PR?"

Cursor cited real SHAs (b25c3a2, 7fab9ac, others), real PR numbers (#77, #76, #81), real authors, with inline canonical URLs throughout: [PR #77](https://github.com/<owner>/<repo>/pull/77), [<sha>](https://github.com/.../commit/<sha>). The host's CLAUDE.md ## Conventions when editing section (added per the project's link discipline policy) was honoured automatically — the prompt did not explicitly ask for link discipline, but Cursor included canonical URLs anyway. This is the acid test for whether CLAUDE.md being "always-applied" actually means CLAUDE.md's contents shape behaviour, not just sit in context. It did. ✅

Test 3 — @wiki-experiment write end-to-end

Prompt: "@wiki-experiment register the current state of develop, including the last merged PR. Apply link discipline."

Cursor:

  • Investigated with real git log and gh pr view.
  • Proposed a type: synthesis page (Develop-Branch-State.md) with up:, related:, tags: frontmatter.
  • Applied link discipline body-wide: 14 canonical https://github.com/.../ URLs in the final page — every PR, every commit short-sha, every branch name carries its canonical link.
  • Updated index_<repo>.md with the new entry.
  • Appended a ## [YYYY-MM-DD] ingest | ... log entry to log_<repo>.md.
  • Committed in two separate commits (page+index, then log) — the one-commit-per-log-entry rule from the wiki maintenance section was honoured.
  • Did NOT push (correctly held the push for explicit OK from the human).

End-to-end functional. ✅

Test 4 — Honest reporting acid test

Cursor's response referenced an open PR (number quoted in the body of Develop-Branch-State.md). The reference was verified against the live GitHub API: gh pr view <num> returned the same title, state, and refs Cursor cited. No fabrication. The wiki page's claims are reproducible. ✅

Two minor observations (non-blocking)

Observation 1 — Commit-without-asking is the designed behaviour. Cursor committed in the wiki sub-repo without a pre-commit stop-and-confirm checkpoint. This was initially flagged as a defect, but the design says otherwise: CLAUDE.md.template's lw:wiki-maintenance section states "Execute these without asking — local commits in the wiki repo are trivially reversible. Push only when explicitly asked." The Claude Code overlay behaves identically. Stop-and-confirm gates live at PUSH, not COMMIT, and Cursor honoured that distinction correctly. Filed here as observation rather than defect.

Observation 2 — Rhetorical "prior snapshot" framing. Cursor's response narrated the write as "refreshed to 2026-06-30 snapshot" and mentioned changes "from the prior 2026-06-29 snapshot", but no such prior snapshot existed on disk (this was the first creation of the page). Not a numerical fabrication — no fake SHAs, no invented PR numbers — but a rhetorical framing of "first creation as if it were an update." Worth tightening in the .cursor/rules/wiki-experiment.mdc spec with a sentence like "do not narrate updates relative to states that do not exist in git history."

Conclusion

The Cursor overlay produces the same wiki-memory experience as Claude Code's overlay, end-to-end, on a real adopting project. The validation gap from the README is closed.

Caveats nameable:

  • The test ran with both overlays installed (claude-code already in place, cursor added on top). The pure-cursor case (cursor on a virgin host, no claude-code) was not exercised in this session — though the design is symmetric and there is no plausible mechanism by which removing claude-code would break cursor's behaviour.
  • The manual install workaround was used because adopt --agent=cursor still refuses at parse-time (issue #65). Validation of the overlay's behaviour is independent of the adopt entry-point; both are now scoped: overlay = validated, adopt entry = work pending.
  • One non-numerical rhetorical framing observation (observation 2 above) is worth tightening in the cursor rules but does not invalidate any of the empirical findings.

Open follow-ups

  1. Tighten .cursor/rules/wiki-experiment.mdc to forbid narrating updates relative to non-existent prior states (observation 2). One-line addition.
  2. Resolve issue #65 (adopt's --agent=cursor parser refusal). The empirical evidence here narrows the remaining work to the adopt entry-point only — the overlay itself is validated. Concrete fix sketch is in the issue's empirical-validation comment: remove the lw_die on adopt.sh:289, decide --force vs --add-agent= semantics for the "add cursor on top of existing adoption" case, add two integration fixtures.
  3. Evolve README Status (open PR opportunity) from "Cursor overlay is shipped but unvalidated in a live session" to "validated end-to-end on a real adopting project (2026-06-30); rules load automatically, link discipline applied, honest reporting honoured." Separate PR; small but durable signal change.
  4. Pure-cursor case validation — a future test where Cursor overlay is installed on a host that does not have Claude Code overlay. The behaviour should be identical (rules are symmetric in design) but has not been empirically confirmed in this pass.

See also

Clone this wiki locally