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. ✅

One minor observation (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.

Correction logged 2026-06-30 (retraction)

An earlier version of this analysis carried a second observation: "rhetorical 'prior snapshot' framing — Cursor narrated 'refreshed to 2026-06-30 snapshot' and referenced a 'prior 2026-06-29 snapshot' that did not exist on disk." That observation was wrong on the analyst's side, not Cursor's. Verified after the fact by running git log --all --oneline -- Develop-Branch-State.md in the host's wiki sub-repo: a real prior commit from 2026-06-29 created the page; Cursor's update narration was accurate. The original observation #2 was a projection (assumption without checking the git log) rather than an empirical finding, and is retracted here. The retraction is preserved in the page history rather than silently removed because the wiki should record corrections honestly — a future reader inheriting this analysis can see that "the second observation was tightened out" and that the verification was: walk the wiki sub-repo's git log for any artefact Cursor narrates as referencing prior state. This same discipline applied to the Verification-Gate would have caught the original error: "no projections, only real script outputs" extends to claims about agent honesty, not only to numerical claims in the page body.

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.
  • An earlier draft of this analysis carried a second observation about a "rhetorical prior-snapshot framing" by Cursor; that observation was retracted after git-log verification proved Cursor's narration accurate (see Correction subsection above).

Open follow-ups

  1. 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.
  2. 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.
  3. 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.
  4. Tighten the Verification Gate's "no projections" clause to extend explicitly to claims about agent behaviour, not only numerical claims in the page body. The original retracted observation passed the gate because the gate currently focuses on numbers; extending its scope to "any claim that could have been verified against a real artefact before being asserted" would catch this class of error.

See also

Clone this wiki locally