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 FamiliarOS MCP tools.

## Status

- **Scope:** Cursor project rules only.
- **Target UX:** CLI-managed project rules in `.cursor/rules/familiaros.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 FamiliarOS 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:

```text
<project>/.cursor/rules/familiaros.mdc
```

Rationale:

- Cursor documents project rules under `.cursor/rules`.
- A dedicated `familiaros.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 FamiliarOS as lightweight status feedback, not as a required step for every task.

Proposed managed file:

```mdc
---
description: Use FamiliarOS MCP tools for lightweight coding-status feedback.
---

<!-- FAMILIAROS:CURSOR_RULES:START -->
# FamiliarOS status feedback

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

- Use `familiaros_say` sparingly for major milestones, blocking states, completion, or when review is needed.
- Prefer `familiaros_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 FamiliarOS.
- Do not spam every internal step; use FamiliarOS only for meaningful progress changes and continue normally if a status update is unnecessary.
- If FamiliarOS is unavailable, continue the coding task without failing.
<!-- FAMILIAROS: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 `familiaros.mdc` file as FamiliarOS-managed only when the managed markers are present:

- `<!-- FAMILIAROS:CURSOR_RULES:START -->`
- `<!-- FAMILIAROS: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 FamiliarOS frontmatter and whitespace;
- recognized FamiliarOS frontmatter is only the frontmatter generated by `buildCursorFamiliarOSRule()` 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/familiaros.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-FamiliarOS 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/familiaros.mdc`. |
| `installed` | no | no | yes | Remove only the managed `familiaros.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/familiaros.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 FamiliarOS managed rule content.

## Package/API design

Extend `@familiaros/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)`
- `buildCursorFamiliarOSRule(options)`
- `readCursorFamiliarOSRules(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:

```bash
familiaros configure --agent cursor --familiar PET_ID --with-rules
familiaros configure --agent cursor --rules-only
familiaros configure --agent cursor --remove-rules
familiaros configure --agent cursor --rules-only --force
```

Semantics:

- Existing `familiaros 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 `familiaros.mdc`.
- `--cwd` keeps existing project-local behavior and points rules at `<cwd>/.cursor/rules/familiaros.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 `--familiar` and must not require FamiliarOS desktop connectivity.
- `--with-rules` continues to require the same inputs as MCP setup, including familiar 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;
- FamiliarOS-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/familiaros.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:

- [x] Confirm current Cursor stable accepts `.cursor/rules/familiaros.mdc`. Official docs document project rules under `.cursor/rules` and support `.mdc`.
- [x] 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.
- [x] 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.
- [x] 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.
- [x] Confirm whether `.cursor/rules/familiaros.md` is equally supported or if `.mdc` is preferred. Official docs support `.md` and `.mdc`; FamiliarOS uses `.mdc` for explicit frontmatter.
- [x] 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 FamiliarOS rule and still connects to the Phase 1 MCP server.
- [ ] Smoke test that the rule does not cause excessive FamiliarOS 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 `@familiaros/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 `familiaros.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:

```bash
pnpm --filter @familiaros/cursor check # passed during implementation
pnpm --filter @familiaros/cli check # passed during implementation
pnpm --filter @familiaros/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?