openpetswithchatandmcp/docs/cursor-phase-2-rules-spec.md

Cursor Phase 2 Implementation Spec: Project Rules Guidance

This spec covers the next Cursor integration phase after MCP-only setup. Phase 2 adds optional project-local Cursor rules so Cursor knows when and how to use the OpenPets MCP tools.

Status

• Scope: Cursor project rules only.
• Target UX: CLI-managed project rules in .cursor/rules/openpets.mdc, with desktop preview/copy support only unless a separate project-picker UX is designed.
• Required before implementation ships: validate current Cursor rule format behavior and record results in this document.
• Oracle approval: approved before implementation; helper, CLI, and desktop phases reviewed between phases.

Goals

1. Give Cursor concise guidance for using OpenPets MCP tools during coding sessions.
2. Keep MCP setup and rules setup separable, explicit, and reversible.
3. Preserve all unrelated Cursor rules and project files safely.
4. Avoid editing user/global Cursor settings because no safe editable user rules path is assumed.
5. Reuse the path-safety, status, preview, backup, and atomic-write posture from Phase 1.

Non-goals

• No Cursor hook/event integration.
• No Cursor extension/plugin.
• No writes to Cursor user rules/settings.
• No writes to ~/.cursor/permissions.json or any allowlist/permission file.
• No broad edits to existing project rules.
• No hidden automatic rule installation from desktop Agent Setup.

Rule file strategy

Default managed file:

<project>/.cursor/rules/openpets.mdc

Rationale:

• Cursor documents project rules under .cursor/rules.
• A dedicated openpets.mdc file avoids modifying user-authored rules.
• Project-local rules can be committed or ignored according to the user's project policy.
• A dedicated file makes ownership, preview, replace, and remove semantics straightforward.

Do not write legacy .cursorrules in Phase 2 unless validation proves it is necessary for current stable Cursor behavior.

Proposed rule content

The rule should be short and tool-oriented. It should teach Cursor to use OpenPets as lightweight status feedback, not as a required step for every task.

Proposed managed file:

---
description: Use OpenPets MCP tools for lightweight coding-status feedback.
---

<!-- OPENPETS:CURSOR_RULES:START -->
# OpenPets status feedback

You may use the OpenPets MCP tools as a brief, safe status channel during meaningful coding work.

- Use `openpets_say` sparingly for major milestones, blocking states, completion, or when review is needed.
- Prefer `openpets_react` over speech for lightweight progress such as thinking, working, testing, success, or error.
- Keep messages short, user-facing, and safe.
- Do not send prompts, tool input/output, code, logs, stack traces, credentials, private file contents, URLs, file paths, or other sensitive content through OpenPets.
- Do not spam every internal step; use OpenPets only for meaningful progress changes and continue normally if a status update is unnecessary.
- If OpenPets is unavailable, continue the coding task without failing.
<!-- OPENPETS:CURSOR_RULES:END -->

Validation must confirm whether the frontmatter keys above are supported in current Cursor. If not, use the simplest documented .mdc form that Cursor accepts. Do not add alwaysApply: true by default unless smoke testing proves it does not cause excessive tool calls during ordinary coding tasks.

Ownership model

Phase 2 should treat the whole openpets.mdc file as OpenPets-managed only when the managed markers are present:

• <!-- OPENPETS:CURSOR_RULES:START -->
• <!-- OPENPETS:CURSOR_RULES:END -->

Exact managed-file rules:

• exactly one start marker and one end marker;
• start marker must appear before the end marker;
• content outside the marker block must be only recognized OpenPets frontmatter and whitespace;
• recognized OpenPets frontmatter is only the frontmatter generated by buildCursorOpenPetsRule() for the current supported format;
• any duplicate markers, reversed markers, user-authored text outside the managed shape, or unknown frontmatter fields must classify as conflict, not needs-update.

Classification:

• missing: .cursor/rules/openpets.mdc does not exist.
• installed: managed file exists and matches expected content.
• needs-update: managed file has the exact managed shape but generated content differs from expected content.
• conflict: file exists but lacks managed markers, has malformed managed markers, has duplicate markers, has unknown frontmatter, or contains non-OpenPets content outside the expected managed shape.
• invalid: unsafe path, symlinked file/parent, non-regular file, oversized file, unreadable file, or invalid parent structure.
• error: unexpected I/O or classification failure.

Action matrix

Status	canInstall	canReplace	canRemove	Write behavior
missing	yes	no	no	Create .cursor/rules/openpets.mdc.
installed	no	no	yes	Remove only the managed openpets.mdc file.
needs-update	yes	yes	yes	Update/replace the managed file.
conflict	no	yes	no	Replace only after explicit user confirmation.
invalid	no	no	no	No writes; user must fix manually.
error	no	no	no	No writes; user must retry or inspect diagnostics.

If removal leaves .cursor/rules empty, Phase 2 may leave the empty directory in place. Do not remove .cursor or other rule files.

Safety requirements

• Accept explicit projectDir inputs for production callers.
• If an explicit rulesPath exists for tests, mark it internal/test-only and still enforce containment under the test project root.
• Resolve the final path and ensure it remains under <project>/.cursor/rules/openpets.mdc.
• Reject symlinks for the rule file and relevant parent directories before writing.
• Reject non-regular files.
• Use an upper size limit for existing rule files before reading. Suggested max: 64 KiB.
• Create .cursor and .cursor/rules with private-ish permissions where supported.
• Write atomically via temp file + rename.
• Create backups before replacing/removing existing managed files.
• Never print unrelated project rule file contents.
• Preview only the OpenPets managed rule content.

Package/API design

Extend @open-pets/cursor with rule helpers rather than duplicating logic in CLI or desktop.

Suggested new file:

• packages/cursor/src/cursor-rules.ts

Suggested exports:

• getCursorProjectRulesPath(projectDir)
• buildCursorOpenPetsRule(options)
• readCursorOpenPetsRules(path)
• classifyCursorRulesStatus(result, path, expected)
• planCursorRulesInstall(path, options, allowReplace?)
• planCursorRulesReplace(path, options)
• planCursorRulesRemove(path)
• executeCursorRulesWrite(plan)
• buildCursorRulesPreview(options)

Shared types should mirror Phase 1 status/action semantics where practical, but rules status should stay separate from MCP status so UI can report them independently.

CLI design

Phase 2 should add explicit rules commands/flags without changing the meaning of existing MCP-only setup unexpectedly.

Recommended commands:

openpets configure --agent cursor --pet PET_ID --with-rules
openpets configure --agent cursor --rules-only
openpets configure --agent cursor --remove-rules
openpets configure --agent cursor --rules-only --force

Semantics:

• Existing openpets configure --agent cursor remains MCP setup.
• --with-rules performs MCP setup and project rules setup.
• --rules-only writes only the project rules file.
• --remove-rules removes only the managed project rules file.
• --force is required to replace a conflicting openpets.mdc.
• --cwd keeps existing project-local behavior and points rules at <cwd>/.cursor/rules/openpets.mdc.
• No global rules CLI behavior in Phase 2.

Flag interaction rules:

• --with-rules, --rules-only, and --remove-rules are mutually exclusive.
• --rules-only and --remove-rules do not require --pet and must not require OpenPets desktop connectivity.
• --with-rules continues to require the same inputs as MCP setup, including pet selection where currently required.
• --with-rules must preflight both the MCP write plan and the rules write plan before writing either file, so a conflict or invalid state does not create surprising partial setup.

The CLI should print:

• target rule path;
• rules status;
• OpenPets-only rule preview;
• backup path when a write removes or replaces an existing file;
• note that Cursor may need reload/restart or a new chat for rule changes to apply.

The CLI should not print unrelated Cursor config or unrelated rule files.

Desktop design

Desktop Agent Setup Phase 2 should not write project-local rules by default because desktop currently configures global Cursor MCP and does not know which project the user wants to modify.

Allowed desktop Phase 2 UX:

• show a Cursor rules preview;
• copy the recommended .cursor/rules/openpets.mdc content;
• explain where to save it in a project;
• link or route users to the CLI command for project-local install.

Do not add desktop project writes unless a separate project-directory picker, path safety review, and Oracle review are completed.

Validation spike before implementation

Record results here before enabling writes:

• Confirm current Cursor stable accepts .cursor/rules/openpets.mdc. Official docs document project rules under .cursor/rules and support .mdc.
• Confirm whether .mdc frontmatter keys description and alwaysApply are accepted and produce the intended always-on guidance behavior. Official docs document description, globs, and alwaysApply; Phase 2 intentionally omits alwaysApply: true by default.
• Confirm whether a plain Markdown body without frontmatter is accepted as a fallback. Official docs document both .md and .mdc; .mdc is retained for frontmatter control.
• Confirm whether Cursor requires reload/restart/new chat before rule changes apply. Official docs do not require reload; UX says Cursor may use changed rules in a new or refreshed chat.
• Confirm whether .cursor/rules/openpets.md is equally supported or if .mdc is preferred. Official docs support .md and .mdc; OpenPets uses .mdc for explicit frontmatter.
• Confirm that project rules do not require permissions file edits. Official docs do not require permissions file edits for project rules.
• Smoke test that Cursor sees the OpenPets rule and still connects to the Phase 1 MCP server.
• Smoke test that the rule does not cause excessive OpenPets tool calls during ordinary coding tasks.

Official docs checked:

• https://cursor.com/docs/rules
• https://cursor.com/help/customization/rules

Implementation review log

• Spec review: Oracle approved after required scope/ownership/CLI clarifications.
• Core helper phase: Oracle approved after adding symlink-file, replace-backup, and invalid-plan/no-write tests.
• CLI phase: Oracle approved to proceed; recommended backup/no-secret CLI assertions were added.
• Desktop phase: Oracle approved to proceed; recommended copy-button/busy handling and snapshot validation were added.

Tests/checks

Add @open-pets/cursor checks for:

• valid rule content generation;
• project rule path resolution;
• missing/installed/needs-update/conflict/invalid/error classification;
• managed marker detection;
• duplicate, reversed, and missing marker classification;
• unmanaged openpets.mdc conflict behavior;
• user text before/after markers and unknown/modified frontmatter conflict behavior;
• no writes on invalid/error/conflict without force;
• explicit replace preserving backups;
• remove only managed file;
• symlink parent/file rejection;
• non-regular and oversized file rejection;
• atomic writes and backup creation;
• CLI contract coverage for --with-rules, --rules-only, --remove-rules, --force, and --cwd.
• desktop contract coverage that rules remain preview/copy only and no desktop rule-write IPC exists.

Run at minimum:

pnpm --filter @open-pets/cursor check # passed during implementation
pnpm --filter @open-pets/cli check # passed during implementation
pnpm --filter @open-pets/desktop check # passed during implementation
pnpm check # passed during implementation

Open questions for Oracle review

1. Should --with-rules become the default before public Cursor announcement, or should rules remain explicit to avoid surprising project file writes?
2. Is alwaysApply: true appropriate for this guidance, or should the rule be agent-requested/manual to reduce context noise?
3. Should the CLI support --remove-rules now, or should removal be a separate future command to keep configure simpler?
4. Is whole-file ownership sufficient, or should Phase 2 support managed-block insertion into a user-authored rules file?
5. Should desktop stay preview/copy-only for rules until a project picker exists?