chore: split cursor rules into focused files and improve tooling

[TomerFi]

Summary

• Split monolithic project-rules.mdc into 6 focused rule files with proper frontmatter, glob patterns, and apply modes (always, file-pattern, intelligent)
• Add gcp-log-analysis.mdc rule with query templates and GCP MCP tool workarounds
• Add cursor-tooling.mdc awareness rule so the agent knows about available agents, commands, and skills
• Add deployment-ops agent for post-deploy health checks and GCP troubleshooting
• Fix serve-docs command to use direct venv binaries instead of source activate
• Fix add-handler skill to use ESM syntax (export default) matching the project

New Rule Files

File	Mode	Scope
project-overview.mdc	Always	Project context, architecture, tech stack
handler-development.mdc	src/handlers/**	Handler contract, lifecycle
testing.mdc	tests/**	Testing patterns, coverage
coding-standards.mdc	**/*.js	Formatting, async, error handling
ci-workflows.mdc	.github/workflows/**	CI/CD practices
gcp-log-analysis.mdc	Intelligent	GCP log queries, MCP workarounds
cursor-tooling.mdc	Always	Lists available agents/commands/skills

Summary by CodeRabbit

• Documentation

  • Added comprehensive guides covering deployment operations, CI/CD workflows, coding standards, tooling, GCP log analysis, handler development, project overview, and testing; removed an older project-rules document.

• Chores

  • Simplified the local docs serve command to be idempotent and easier to run.

• Refactor

  • Updated handler module examples to a more modern module export style.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

Splits and expands the monolithic project rules into focused Cursor documentation: adds deployment ops, CI workflows, coding standards, GCP log analysis, handler development, project overview, testing, and tooling docs; removes the old project-rules.mdc; tweaks serve-docs venv handling and updates add-handler example to use an ES module default export.

Changes

Cohort / File(s)	Summary
Deployment Ops Agent /.cursor/agents/deployment-ops.md	New doc describing deployment configuration, capabilities, post-deploy health checks, troubleshooting playbook, and verification steps for the Cloud Run / Cloud Functions Gen2 deployment.
CI / Coding / Testing Rules /.cursor/rules/ci-workflows.mdc, /.cursor/rules/coding-standards.mdc, /.cursor/rules/testing.mdc	Adds CI workflow conventions, JavaScript coding standards, and testing guidelines (globs, rules, and examples).
GCP Log Analysis & Tooling /.cursor/rules/gcp-log-analysis.mdc, /.cursor/rules/cursor-tooling.mdc	New guidance for GCP log queries, MCP limitations, and a registry of Cursor agents/commands/skills.
Handler Development & Project Overview /.cursor/rules/handler-development.mdc, /.cursor/rules/project-overview.mdc	New handler lifecycle, handler contract (match/run), registration details, and a concise project architecture/tech-stack overview.
Removed Monolith /.cursor/rules/project-rules.mdc	Deleted the prior monolithic project rules file; content split across new focused docs.
Command & Skill Samples /.cursor/commands/serve-docs.mdc, /.cursor/skills/add-handler/SKILL.md	serve-docs adjusted to create/use .venv and invoke pip/mkdocs via explicit venv paths; add-handler sample switched from CommonJS samples to ES module-style export default {match, run}.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• chore: enhance project with ai tooling and cursor integration #795 — Overlapping updates to Cursor docs and examples (serve-docs, add-handler, and project rules-related documentation).

Poem

🐰 I hopped through docs with careful paws,

I split the rules and fixed the flaws.
Handlers, tests, and deploys set free,
A tidy burrow for you and me.
Sniff, nibble, commit — hooray for me!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'chore: split cursor rules into focused files and improve tooling' accurately summarizes the main changes: refactoring monolithic cursor rules into focused files and enhancing tooling documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/cursor-config-improvements

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.21%. Comparing base (35a501e) to head (c374521).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #823   +/-   ##
=======================================
  Coverage   99.21%   99.21%           
=======================================
  Files           8        8           
  Lines        1022     1022           
=======================================
  Hits         1014     1014           
  Misses          8        8           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

.cursor/rules/handler-development.mdc (1)

9-16: Optional: add error-handling rule to complete the handler contract.

The retrieved learnings include a rule — "Always catch and report API errors in handler logic" — that isn't surfaced here. The rule file is the primary guidance an AI agent will consult when working in src/handlers/, so omitting it risks newly generated handlers silently swallowing errors.

✏️ Suggested addition

 Every handler in `src/handlers/` MUST export:
 1. `match(context)` - Returns boolean, determines if handler should run
 2. `run(context, config, startedAt)` - Async function that executes handler logic
+3. Always catch and report API errors inside `run()` — do not let errors propagate silently

Based on learnings: "Applies to src/handlers/*.js : Always catch and report API errors in handler logic."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.cursor/rules/handler-development.mdc around lines 9 - 16, Add a mandatory
error-handling rule to the handler spec: require that every handler exporting
match(context) and run(context, config, startedAt) must catch and report API
errors (e.g., network/HTTP errors) inside run, log the error details, and ensure
the PR lifecycle is honored by updating the check-run to a completed state with
an appropriate failing conclusion when an error occurs; reference match(context)
and run(context, config, startedAt) in the rule and explicitly state that
handlers must not silently swallow exceptions but must surface them to
processLogger/check-run update logic.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.cursor/agents/deployment-ops.md:
- Line 5: Add a blank line after each second-level heading to satisfy
markdownlint MD022: insert an empty line immediately after the "## Environment",
"## Capabilities", and "## Post-Deploy Health Check" headings so that each
heading is followed by a blank line before the next paragraph or content.
- Line 47: Edit the line that reads "Compare revision name to previous to
confirm new revision is active" and replace the phrase "previous to" with
"before" so it reads "Compare revision name to before to confirm new revision is
active" (better: "Compare revision name to the previous one to confirm the new
revision is active"); update the sentence text in
.cursor/agents/deployment-ops.md accordingly.

In @.cursor/rules/cursor-tooling.mdc:
- Around line 8-10: The file has a duplicated heading—use the plural "## Agents"
block (the existing "## Agents (.cursor/agents/)" list) and move the misplaced
`deployment-ops` entry from the second "## Agent" heading into that first list,
then remove the second "## Agent" heading entirely so all agent entries
(including `code-reviewer`, `docs-writer`, and `deployment-ops`) live under a
single consistent "## Agents" section.

---

Nitpick comments:
In @.cursor/rules/handler-development.mdc:
- Around line 9-16: Add a mandatory error-handling rule to the handler spec:
require that every handler exporting match(context) and run(context, config,
startedAt) must catch and report API errors (e.g., network/HTTP errors) inside
run, log the error details, and ensure the PR lifecycle is honored by updating
the check-run to a completed state with an appropriate failing conclusion when
an error occurs; reference match(context) and run(context, config, startedAt) in
the rule and explicitly state that handlers must not silently swallow exceptions
but must surface them to processLogger/check-run update logic.

[TomerFi]

@coderabbitai resolve

[snyk-io]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.cursor/agents/deployment-ops.md:
- Line 30: Several sub-headings inside the document (notably "### Service not
ready" under "Troubleshooting Playbook" and the "## Deployment Verification"
section) are missing a blank line after the heading which triggers MD022; fix by
inserting a single empty line immediately after each affected heading (e.g.,
after "### Service not ready", after other "###" sub-headings referenced on
lines 34, 38, 43, and after "## Deployment Verification" on lines 47-48) so
every heading is followed by a blank line before the next content block.

[coderabbitai]

✅ Actions performed

Comments resolved. Auto-approval is disabled; enable reviews.request_changes_workflow to approve automatically.