cursor.md

Cluas — Cursor Project Guide

Mode: Surgical (1)

Cursor should follow all rules below unless explicitly overridden.

---

1. Operational Mode

Surgical Mode Rules

• Do not refactor unless explicitly instructed.
• Do not modify multiple files unless I list them.
• Never modify architecture, directories, or file names without approval.
• Suggest changes through tickets or plans before acting.
• Show diffs before application.
• When uncertain, ask before reading or writing.

Scope Minimization

• Default to reading only the file(s) mentioned in the prompt.
• If the task affects a directory, request confirmation before a bulk read.
• Use subfolder-level cursor.md files to override local behavior.

---

2. Project Overview

Cluas is a multi-agent research assistant with:

• Four character agents with distinct personas (src/characters)
• An MCP-based tool layer (src/cluas_mcp)
• A shared utility layer (src/utils)
• A Gradio-based UI (src/gradio)
• An orchestration layer (src/orchestrator.py)
• Local JSON-based memory and cache (src/data)

---

3. Repository Structure

src/ characters/ # persona logic cluas_mcp/ # MCP servers & entrypoints academic/ common/ domain/ news/ observation/ web/ data/ # stored memory & cache (never modify) gradio/ # UI utils/ # shared utilities orchestrator.py # high-level orchestrator

---

4. Safe Editing Areas

Cursor may edit:

• src/characters/*
• src/cluas_mcp/* except where noted as fragile
• src/gradio/app.py
• src/utils/*
• Implementation-level code supporting tools
• Small, isolated improvements

---

5. Restricted / Fragile Areas

• src/orchestrator.py — changes require explicit approval
• src/data/* — never modify programmatically or structurally
• Any file not listed as safe
• Any control-plane glue code unless specifically permitted
• Any config or naming conventions

---

6. Architectural Notes

Characters Layer

• Each file defines a persona with specific expertise.
• Output formatting conventions must remain stable.
• Do not merge personas; do not modify persona names or roles.

MCP Layer

Contains specialized tool entrypoints:

• academic/: arXiv, PubMed, Semantic Scholar fetchers
• news/: news API search
• observation/: bird/weather observational tools
• web/: trending and general web search
• common/: shared HTTP, memory, cache logic

Rules:

• Do not alter API endpoint URLs without instruction.
• Network logic should be consistent across tools.
• Retry, caching, and rate-limiting must remain stable.

Utilities

• model_list_groq.py and others should remain small and self-contained.
• Avoid large rewrites; maintain consistency.

Gradio UI

• Keep user-facing function names and event wiring intact.

Orchestrator

• Treat as a fragile, single-source-of-truth.
• Do not rewrite flow control, dispatch, or agent coordination without approval.

---

7. Code Conventions

General

• Follow existing stylistic patterns.
• Prefer explicitness over magic.
• Use docstrings consistent with current style.

Import rules

• Maintain import locality.
• Avoid introducing top-level cross-layer dependencies.

Error handling

• Follow existing try/except patterns.
• Do not remove error metadata or context.

---

8. Ticket Workflow (Required Before Major Changes)

When asked for anything non-trivial:

1. Produce a numbered list of proposed tickets.
2. Each ticket contains:
   • Goal
   • Impacted files
   • Expected risk
   • Estimated complexity
3. Wait for explicit approval before generating code.

Example ticket structure:

[Ticket 1] Improve arXiv query building Files: src/cluas_mcp/academic/arxiv.py Risk: Low Complexity: Low Notes: Only adjust parsing logic.

---

9. Diff Workflow

For all modifications:

• Always show a diff preview.
• Only write code after explicit approval.
• Keep diffs minimal, targeted, and reversible.
• Do not auto-format unrelated areas.

---

10. Performance & Credit Preservation

• Do not scan the whole repo without being asked.
• Limit reads to single files or small folders.
• Ask before reading directories > 10 files.
• Prefer incremental review over full-context analysis.
• Avoid speculative work.

---

11. Subfolder cursor.md Rules

If a directory contains its own cursor.md:

• That file overrides root rules for that directory only.
• Root-level rules apply everywhere else.
• Local rules must remain compatible with Surgical Mode.

---

12. MCP Tool Guidelines

When editing MCP server/entrypoint modules:

• Maintain signatures required by the MCP spec.
• Preserve tool names, IDs, argument shapes.
• Keep responses deterministic unless instructed otherwise.
• Do not alter output contract formats.
• Keep HTTP client logic consistent across tools.

---

13. Persona/Character Guidelines

• Personas have fixed tone, knowledge windows, and behavioral constraints.
• Do not alter identity, speech patterns, or output styles.
• Internal logic may be improved but not reimagined.

---

14. Orchestrator Guidelines (High-Risk Zone)

Before editing orchestrator.py, always:

1. Generate a plan.
2. Produce tickets.
3. Wait for explicit approval.

Disallowed without authorization:

• Rewiring tool routing
• Changing conversation state logic
• Modifying persona dispatch
• Changing execution order or concurrency rules

---

15. Testing / Validation Rules

• Follow current usage patterns; do not introduce new frameworks.
• Keep tests inline or minimal.
• Ensure MCP tools remain usable without breaking contract.

---

16. Prompt Templates (For Cursor Tasks)

General Improvement

“Review only this file: . Identify small improvements. No refactors.”

Write a patch

“Prepare a diff for tickets 1 and 2 only.”

Ask for a plan

“Before editing, give me a plan and a ticket list.”

Isolated folder work

“Limit analysis to src/cluas_mcp/news.”

---

17. Maintenance Guidelines

• Keep modifications atomic.
• Maintain existing naming conventions.
• Avoid unnecessary abstraction.
• Keep folder boundaries clean.
• Preserve backward compatibility.

---

18. Quick Summary for Cursor

• Surgical Mode only.
• Minimal diffs.
• Ask before reading large scopes.
• Never refactor without permission.
• Use tickets + plans before substantial work.
• Preserve architecture, personas, orchestrator flow.
• Subfolder cursor.md files override root rules.