Rules sync and Go standards

[jbsmith7741]

Quality check

• Documentation included
• Test coverage

Summary

Adds org-wide agent behavior rules, tightens Go testing conventions, and introduces multi-project rule sync across registered repositories.

• Agent behavior: New agent-behavior.mdc (alwaysApply) for rule precedence over surrounding code and asking on ambiguity; registered in ORG_RULES.
• Go testing: Function-scoped test naming (TestFunction / TestStruct_Method), strict table-or-inline (no hybrid), concise wording in go-testing.mdc.
• Multi-project sync: install.sh installs canonical rules-source/ and runs --sync-all by default; install-rules.sh gains projects.registry, --sync-all, --list, --unregister, --purge, and link-to-copy fallback; uninstall.sh adds --purge-project-rules.
• Docs: README registry format, toolkit-agnostic “Rules applied” user rule, commands/commit.md conventional commit type definitions, and commands/install_rules.md / docs/cursor.md multi-project workflow.

[qodo-code-review]

PR Summary by Qodo

Add org-wide agent rules and multi-project Cursor rules sync

✨ Enhancement 📝 Documentation 🕐 40+ Minutes

AI Description

• Add always-on org agent behavior rules and register them via ORG_RULES.
• Tighten Go testing standards for symbol-scoped naming and single-style (table vs inline) tests.
• Introduce a projects registry and default sync-all workflow for rule installs/uninstalls across
 repos.

Diagram

graph TD
  A["install.sh"] --> B["~/.cursor/ai-toolkit/rules-source/"] --> D["install-rules.sh"] --> F["<project>/.cursor/rules/ai-toolkit/"]
  D --> C["~/.cursor/ai-toolkit/projects.registry"] --> E["Registered projects"] --> F
  G["uninstall.sh"] --> D --> F

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Rely on Cursor Team Rules / Remote Rules only

• ➕ Centralized updates without per-user scripts or symlink/copy decisions
• ➕ Avoids local registry format and related corruption/edge cases
• ➖ Not always available (requires org/team configuration) and may not cover all workflows
• ➖ Less control for offline/dev-box environments; harder to tailor per-repo stack filters

2. Vendor rules into each repo (subtree/submodule or copied directory)

• ➕ Rules are versioned and reviewed per repo; no external registry needed
• ➕ CI and code review naturally catch rule changes
• ➖ Higher ongoing maintenance to update rules across many repos
• ➖ Harder to keep org-wide rules consistent without an additional automation layer

3. Store registry as structured data (JSON/YAML) + locking

• ➕ More robust parsing/escaping than pipe-delimited lines; easier future extension (timestamps, labels, last sync)
• ➕ Can add file locking to avoid concurrent updates during sync-all
• ➖ Adds dependencies/complexity for a small shell tool unless you also introduce jq/python
• ➖ Not strictly necessary if current format remains small and well-scoped

Recommendation: The PR’s registry-driven sync (triggered by install.sh and backed by a canonical rules-source) is a pragmatic middle ground: it keeps per-project rules (matching Cursor’s realities) while making updates scalable across many repos. If the registry grows in usage, consider a follow-up to harden concurrency (basic lockfile) and possibly migrate the registry format, but the current approach is a good fit for bash-only distribution.

Files changed (10) +624 / -116

Enhancement (5) +528 / -90

install.shInstall canonical rules-source and auto-sync registered project rules +52/-10

Install canonical rules-source and auto-sync registered project rules

• Adds rules/ validation and installs rules into ~/.cursor/ai-toolkit/rules-source alongside scripts. Changes script installation to link/copy individual files and introduces --no-sync-rules to skip running install-rules.sh --sync-all after installation.

install.sh

agent-behavior.mdcAdd alwaysApply org-wide agent behavior rule for precedence and ambiguity +13/-0

Add alwaysApply org-wide agent behavior rule for precedence and ambiguity

• Introduces a new always-on rule stating that installed rules override surrounding code and that the agent should ask the user when behavior is ambiguous. Designed to apply across all projects via ORG_RULES.

rules/agent-behavior.mdc

go-testing.mdcTighten Go test naming and enforce single style per test function +7/-6

Tighten Go test naming and enforce single style per test function

• Adds symbol-scoped test naming guidance (TestFunction / TestStruct_Method) and clarifies when behavioral names are acceptable. Replaces prior generic guidance with an explicit rule: per Test… function, use either a full table/trial pattern or fully inline tests—never a hybrid.

rules/go-testing.mdc

install-rules.shAdd projects.registry, sync-all/list/unregister/purge commands, and link→copy fallback +426/-69

Add projects.registry, sync-all/list/unregister/purge commands, and link→copy fallback

• Reworks the installer to prefer a canonical ~/.cursor/ai-toolkit/rules-source and adds a persistent registry of projects (path|filter|mode). Implements multi-project operations (sync-all, list, unregister, purge, purge-all), auto-registration on install (opt-out), and per-project fallback from symlink mode to copy mode when linking fails.

scripts/install-rules.sh

uninstall.shAdd optional purge of project rules across registered repos before uninstall +30/-5

Add optional purge of project rules across registered repos before uninstall

• Adds --purge-project-rules to call install-rules.sh --purge-all before removing global toolkit files. Updates messaging to warn about dangling symlinks for link-mode projects when purging is skipped.

uninstall.sh

Documentation (4) +95 / -26

README.mdDocument registry-based multi-project rules sync and attribution guidance +31/-14

Document registry-based multi-project rules sync and attribution guidance

• Updates install/uninstall docs to describe canonical rules-source, project registration, and default sync behavior. Adds explicit projects.registry format and expands the suggested user rule text to be toolkit-agnostic and avoid guessing rule names.

README.md

commit.mdAlign commit message guidance with Conventional Commits type-first format +14/-4

Align commit message guidance with Conventional Commits type-first format

• Switches the subject line template to <type>(<scope>) and expands allowed type definitions (commitizen-go oriented). Clarifies scope intent and when to use feat vs fix vs chore.

commands/commit.md

install_rules.mdDocument registration and multi-project management flags for install-rules +22/-7

Document registration and multi-project management flags for install-rules

• Updates command guidance to note auto-registration (opt-out via --no-register) and adds documentation for list/sync/unregister/purge workflows. Documents the projects.registry format and reiterates manifest-driven stacks.

commands/install_rules.md

cursor.mdAdd multi-project sync workflow documentation and paths table +28/-1

Add multi-project sync workflow documentation and paths table

• Expands Cursor setup docs with registry/list/sync examples and explains that install.sh refreshes rules-source and syncs registered projects by default. Adds a dedicated section describing register/sync/unregister/purge/uninstall behaviors and pitfalls (dangling symlinks).

docs/cursor.md

Other (1) +1 / -0

manifest.shRegister agent-behavior.mdc as an org rule +1/-0

Register agent-behavior.mdc as an org rule

• Adds agent-behavior.mdc to ORG_RULES so it is installed alongside stack-selected rules during project installs and sync operations.

rules/manifest.sh

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Registry wiped on install ✓ Resolved 🐞 Bug ≡ Correctness

Description

install.sh deletes ${HOME}/.cursor/ai-toolkit (BIN_TARGET) during install, which removes
projects.registry and loses all registered projects. The later sync_registered_projects call
then runs install-rules.sh --sync-all with an empty/missing registry, so project rules cannot be
synced.

Code

install.sh[R121-123]

  mkdir -p "$(dirname "${BIN_TARGET}")"
  rm -rf "${BIN_TARGET}"
+  mkdir -p "${BIN_TARGET}"

Evidence

install.sh defines REGISTRY_FILE under BIN_TARGET and then deletes BIN_TARGET in
install_bin(). scripts/install-rules.sh also points REGISTRY_FILE at the same location and
cmd_sync_all requires it to enumerate projects, so wiping it breaks multi-project sync.

install.sh[10-13]
install.sh[116-124]
install.sh[149-157]
scripts/install-rules.sh[16-20]
scripts/install-rules.sh[302-322]
scripts/install-rules.sh[542-552]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`install.sh` rebuilds `${HOME}/.cursor/ai-toolkit` by `rm -rf`-ing `BIN_TARGET` inside `install_bin()`. The new registry file (`projects.registry`) lives inside `BIN_TARGET`, so every reinstall wipes the registry and defeats `--sync-all`.

### Issue Context
- Registry path is `${HOME}/.cursor/ai-toolkit/projects.registry`.
- `scripts/install-rules.sh --sync-all` depends on that registry to know what projects to update.

### Fix Focus Areas
- install.sh[10-13]
- install.sh[116-157]

### Suggested fix approach
1. **Preserve the registry file before deleting `BIN_TARGET`**:
  - If `${REGISTRY_FILE}` exists, copy/move it to a temp location.
2. Perform the existing rebuild (`rm -rf BIN_TARGET`, recreate, reinstall scripts/rules-source).
3. **Restore the registry file** back into `${BIN_TARGET}` after rebuild.
4. Ensure permissions remain correct (regular text file).

(Alternative: move the registry to a path outside `BIN_TARGET`, but then update both `install.sh` and `scripts/install-rules.sh` constants accordingly.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---