docs: agentic rules and commands #1101
Open
+7,202
−1,222
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Introduced `CursorCLI` for validating rules and commands against Tux project standards. - Added validation logic for rule frontmatter, description, content, and command structure. - Integrated a new pre-commit hook to validate cursor rules and commands during commits.
- Introduced new markdown files for linting, refactoring, reviewing diffs, and database operations. - Each file outlines steps, checklists, and error handling for maintaining code quality in the Tux project. - Enhanced documentation for Docker commands and testing procedures to streamline development processes.
- Changed the entry command for the cursor validation hook to include 'validate' for improved clarity and functionality. - Removed unnecessary arguments from the hook configuration to streamline the validation process.
- Added a new `RulesCLI` for validating rules and commands against Tux project standards. - Updated pre-commit configuration to use the new validation command. - Enhanced the `pyproject.toml` to include the rules CLI entry point. - Refactored existing code to integrate the new validation logic and ensure proper command structure.
- Added a comprehensive catalog of all Cursor rules and commands for the Tux project, enhancing clarity and accessibility. - Updated individual rule files with detailed descriptions, best practices, and anti-patterns for various components, including database, modules, and security. - Introduced new files for database migrations, queries, and service patterns, ensuring a structured approach to database operations. - Enhanced documentation for error handling, logging, and testing patterns to improve overall code quality and maintainability. - Removed outdated overview files and streamlined the organization of rules for better navigation and usability.
- Introduced new markdown templates for commands and rules to standardize documentation practices. - The command template includes sections for overview, steps, error handling, and checklists. - The rule template features patterns, best practices, anti-patterns, and examples to guide users in implementation. - These templates aim to enhance clarity and consistency in documenting commands and rules within the Tux project.
…nd rules - Introduced two new guides: "Creating Cursor Commands" and "Creating Cursor Rules" to provide step-by-step instructions for developers. - Each guide includes quick start sections, detailed steps, best practices, and templates to standardize the creation of commands and rules within the Tux project. - Updated the main developer guides index to include links to the new guides, enhancing accessibility and organization of documentation resources.
- Introduced a new README file detailing the structure and usage of Cursor's rules and commands system. - Provided an overview of rules and commands, their organization by domain and category, and instructions for usage. - Included links to comprehensive guides and resources for contributing to Cursor rules and commands, enhancing developer onboarding and documentation accessibility.
- Added a new section detailing Cursor's rules and commands system, including their organization and usage. - Included validation commands and links to comprehensive guides for creating rules and commands. - Updated development workflow to incorporate rules validation as a step before committing changes. - Improved documentation structure for better clarity and accessibility of Cursor-related resources.
- Included links to "Creating Cursor Rules" and "Creating Cursor Commands" in the developer guides index. - These additions enhance the documentation structure and provide developers with essential resources for implementing Cursor functionalities.
Contributor
Reviewer's GuideIntroduces a Cursor-focused rules and commands system into the Tux repo, including a Sequence diagram for rules validation via pre-commit and CLIsequenceDiagram
actor Developer
participant Git as GitPreCommit
participant PreCommit as PreCommitHook
participant Uv as UvRunner
participant RulesEntrypoint as ScriptsRulesMain
participant RulesCLI as RulesCLI
participant FS as FileSystem
Developer->>Git: git commit
Git->>PreCommit: run hooks
PreCommit->>PreCommit: validate-rules hook
PreCommit->>Uv: uv run rules validate --rules-dir .cursor/rules --commands-dir .cursor/commands
Uv->>RulesEntrypoint: scripts.rules:main()
RulesEntrypoint->>RulesCLI: RulesCLI()
RulesEntrypoint->>RulesCLI: cli.run()
RulesCLI->>FS: list .cursor/rules/*.mdc
loop For each rule file
RulesCLI->>FS: read rule file
RulesCLI->>RulesCLI: _validate_rule(file_path)
end
RulesCLI->>FS: list .cursor/commands/**/*.md
loop For each command file
RulesCLI->>FS: read command file
RulesCLI->>RulesCLI: _validate_command(file_path)
end
RulesCLI->>RulesCLI: _print_validation_summary(...)
alt validation errors
RulesCLI-->>Uv: exit code 1
Uv-->>PreCommit: non-zero exit
PreCommit-->>Git: hook failed
Git-->>Developer: commit blocked, show errors
else all valid
RulesCLI-->>Uv: exit code 0
Uv-->>PreCommit: success
PreCommit-->>Git: hook passed
Git-->>Developer: commit proceeds
end
Class diagram for the new RulesCLI validation systemclassDiagram
class BaseCLI {
+str name
+str description
+console
+app
+_command_registry
+__init__(name, description)
+add_command(func, name, help_text)
+run()
}
class Command {
+str name
+callable func
+str help_text
+__init__(name, func, help_text)
}
class RulesCLI {
+__init__()
-_setup_command_registry() void
-_setup_commands() void
-_check_rule_frontmatter(file_path, content) tuple~list~str~~, str or None~
-_check_rule_description(file_path, frontmatter, is_spec, is_reference) list~str~
-_check_rule_content(file_path, content, frontmatter_end, is_spec, is_reference, is_docs_rule) list~str~
-_validate_rule(file_path) list~str~
-_validate_command(file_path) list~str~
+validate(rules_dir, commands_dir) void
-_print_validation_summary(rule_files, cmd_files, all_errors) void
}
class TyperApp {
+callback()
+command()
+__call__()
}
BaseCLI <|-- RulesCLI
RulesCLI o--> Command : registers
RulesCLI o--> TyperApp : uses app
class RulesModule {
+app
+main() void
}
RulesModule ..> RulesCLI : instantiates
RulesModule ..> TyperApp : exposes as app
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey there - I've reviewed your changes - here's some feedback:
- In
scripts/rules.py,validate()currently exits with an error if either the rules or commands directory is missing; consider treating a missing directory as an empty set (or making each optional) so validation can still run in repos/branches that only use one of the two. - The extension checks in
_validate_ruleand_validate_commandare redundant because you already filter files withrglob('*.mdc')andrglob('*.md'); you can remove those checks to simplify the validators. - You construct
RulesCLItwice (once for the module-levelappand again inmain()); reusing a single instance or delegatingmain()to the existingappwould reduce duplicate setup logic.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `scripts/rules.py`, `validate()` currently exits with an error if either the rules or commands directory is missing; consider treating a missing directory as an empty set (or making each optional) so validation can still run in repos/branches that only use one of the two.
- The extension checks in `_validate_rule` and `_validate_command` are redundant because you already filter files with `rglob('*.mdc')` and `rglob('*.md')`; you can remove those checks to simplify the validators.
- You construct `RulesCLI` twice (once for the module-level `app` and again in `main()`); reusing a single instance or delegating `main()` to the existing `app` would reduce duplicate setup logic.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Contributor
📚 Documentation Preview
|
Codecov Report✅ All modified and coverable lines are covered by tests. ❌ Your project check has failed because the head coverage (40.13%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage. Additional details and impacted files@@ Coverage Diff @@
## main #1101 +/- ##
=======================================
Coverage 40.13% 40.13%
=======================================
Files 205 205
Lines 14628 14628
Branches 1722 1722
=======================================
Hits 5871 5871
Misses 8757 8757 ☔ View full report in Codecov by Sentry. |
…dling - Added autofix and autoupdate commit message formats for pre-commit hooks. - Excluded validation rules from the pre-commit checks to streamline the process. - Updated Python version specification to 3.13 for consistency.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request
Description
Provide a clear summary of your changes and reference any related issues. Include the motivation behind these changes and list any new dependencies if applicable.
If your PR is related to an issue, please include the issue number below:
Related Issue: Closes #
Type of Change:
Guidelines
My code follows the style guidelines of this project (formatted with Ruff)
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation if needed
My changes generate no new warnings
I have tested this change
Any dependent changes have been merged and published in downstream modules
I have added all appropriate labels to this PR
I have followed all of these guidelines.
How Has This Been Tested? (if applicable)
Please describe how you tested your code. e.g describe what commands you ran, what arguments, and any config stuff (if applicable)
Screenshots (if applicable)
Please add screenshots to help explain your changes.
Additional Information
Please add any other information that is important to this PR.
Summary by Sourcery
Integrate a Cursor-based rules and commands system into the project and document how to use and validate it as part of the standard development workflow.
New Features:
uv run rules …) for validating Cursor rules and commands and expose it via the project scripts entry point..cursor/commands.Enhancements:
Build:
pyproject.tomlso it can be invoked viauv run rules.CI:
uv run rules validateon.cursorrule and command changes to enforce consistency and standards.Documentation:
.cursor/README.mdexplaining the rules and commands system, directory structure, usage patterns, and contribution guidelines.