├── LICENSE ├── .cursor └── rules │ ├── rules.mdc │ ├── project-config.mdc │ ├── user-rules-template.mdc │ ├── cursor-rules-management.mdc │ ├── architecture.mdc │ ├── workflow-state.mdc │ └── epics.mdc ├── package.json ├── .github ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── release-request.md ├── release-template.md └── pull_request_template.md ├── CODE_OF_CONDUCT.md ├── docs ├── README.md ├── smart-detection-examples.md ├── release-management.md ├── ai-safe-commits.md ├── architecture.md ├── faq.md ├── rule-testing.md └── for-developers.md ├── RELEASE_SYSTEM.md ├── CHANGELOG.md ├── scripts ├── validate-rules.js └── validate-docs.js ├── examples ├── README.md └── frontend-react-typescript │ └── README.md └── CONTRIBUTING.md /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Faruk Brbovic 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.cursor/rules/rules.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: 3 | globs: 4 | alwaysApply: true 5 | --- 6 | # Cursor Rule Organization and Codification 7 | This file contains all cursor rules that should be followed during development. When asked to remember a cursor rule, it will be added to the appropriate section below. All rules in this file must always be followed unless explicitly overridden by the user. 8 | 9 | ## Rule Locations and Scope 10 | 11 | - **/**: Contains rules and guidelines that apply to the entire application, across all workspaces and domains. Use this location for any rule that should be remembered and enforced globally. 12 | - **/[[domain]]**: e.g. Contains rules and guidelines that apply only to the [[DOMAIN]] portion of the application. Use this location for rules specific to the [[DOMAIN]] codebase, 13 | 14 | ## Best Practices 15 | - **All Cursor rules must use the `.mdc` extension.** Do not use `.md` or other extensions for rules files. 16 | - Always write and update rules in the correct workspace according to their intended scope. 17 | - Reference global rules from workspace-specific rules if needed, but do not duplicate content. 18 | - When in doubt, prefer to place rules in the most restrictive (specific) workspace that matches their scope. 19 | 20 | --- 21 | 22 | This meta-rule ensures clarity and consistency in rule management across the project. Update this file if the rule organization strategy changes. 23 | 24 | ## Rule addition instructions 25 | When the user asks to "remember a cursor rule", add it to the appropriate section below or create a new subsection if needed. 26 | Always include: 27 | - Clear rule description 28 | - Context for when it applies 29 | - Any exceptions or special cases 30 | - Date added (as a commnet) 31 | - Keep the rule as short as possible without sacrificing clarity and understanding 32 | 33 | IMPORTANT: If below rules get larger than 500 lines, break up the rules into meaningful groups and store them as separate files in .cursor/rules directory starting with rules- prefix. Then make sure to add the reference in this file to it with short instructions on how to read it and follow it. 34 | 35 | ## Development Rules 36 | <-- This area should store all the rules, to be only completed and managed by AI --> 37 | 38 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "cursor-rule-framework", 3 | "version": "1.2.1", 4 | "description": "Professional Cursor AI Rule Framework for 'Vibe Coding' - Co-Built by Engineers & AI, for Engineers & AI", 5 | "main": "README.md", 6 | "repository": { 7 | "type": "git", 8 | "url": "git+https://github.com/fbrbovic/cursor-rule-framework.git" 9 | }, 10 | "keywords": [ 11 | "cursor", 12 | "cursor-ai", 13 | "ai-development", 14 | "rules", 15 | "framework", 16 | "development", 17 | "automation", 18 | "vibe-coding", 19 | "ai-assistant", 20 | "productivity", 21 | "workflow", 22 | "epic-planning", 23 | "architecture", 24 | "pair-programming" 25 | ], 26 | "author": { 27 | "name": "fbrbovic", 28 | "url": "https://github.com/fbrbovic" 29 | }, 30 | "license": "MIT", 31 | "bugs": { 32 | "url": "https://github.com/fbrbovic/cursor-rule-framework/issues" 33 | }, 34 | "homepage": "https://github.com/fbrbovic/cursor-rule-framework#readme", 35 | "engines": { 36 | "node": ">=16.0.0" 37 | }, 38 | "files": [ 39 | ".cursor/", 40 | "docs/", 41 | "examples/", 42 | "README.md", 43 | "LICENSE", 44 | "CHANGELOG.md", 45 | "CONTRIBUTING.md", 46 | "CODE_OF_CONDUCT.md" 47 | ], 48 | "scripts": { 49 | "release": "npm run release:patch", 50 | "release:patch": "npm version patch && git push --follow-tags", 51 | "release:minor": "npm version minor && git push --follow-tags", 52 | "release:major": "npm version major && git push --follow-tags", 53 | "release:prerelease": "npm version prerelease && git push --follow-tags", 54 | "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s", 55 | "version": "npm run changelog && git add CHANGELOG.md", 56 | "validate": "npm run validate:rules && npm run validate:docs", 57 | "validate:rules": "node scripts/validate-rules.js", 58 | "validate:docs": "node scripts/validate-docs.js", 59 | "test": "echo \"No tests specified yet\" && exit 0", 60 | "lint": "echo \"No linting configured yet\" && exit 0", 61 | "format": "echo \"No formatting configured yet\" && exit 0" 62 | }, 63 | "devDependencies": { 64 | "conventional-changelog-cli": "^4.1.0", 65 | "semver": "^7.5.4", 66 | "js-yaml": "^4.1.0" 67 | }, 68 | "publishConfig": { 69 | "access": "public" 70 | }, 71 | "funding": { 72 | "type": "github", 73 | "url": "https://github.com/sponsors/fbrbovic" 74 | }, 75 | "directories": { 76 | "doc": "docs", 77 | "example": "examples" 78 | }, 79 | "config": { 80 | "release": { 81 | "conventional-commits": true, 82 | "generate-changelog": true 83 | } 84 | } 85 | } -------------------------------------------------------------------------------- /.cursor/rules/project-config.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: 3 | globs: 4 | alwaysApply: true 5 | --- 6 | # project-config.md 7 | Last-Updated: 2025-06-07 8 | 9 | ## Project Goal 10 | e.g. Build an enterprise ready platform that allows users to build and launch websites 11 | 12 | ## Tech Stack 13 | - **Language(s):** e.g TypeScript , Javascript 14 | - **Framework(s):** e.g. Nuxt.js, Encore TS, Vue.js 15 | - **Build / Tooling:** e.g. pnpm, Turborepo, docker 16 | - **Monorepo Structure:** e.g Turborepo-managed workspace with apps/frontend and apps/backend 17 | 18 | ## Critical Patterns & Conventions 19 | - When ever possible recommend building an AI-First solution, where solution uses an AI to make the user experience easy and streamlines. 20 | - Prioritize using open source packages whenever you can instead of building your own. Preferred package repository is npm, but do also search for open source github repos. 21 | - Prioritize `@Docs` for internal documentation and `@Web` for external resources. 22 | - Use `@Git` and `@Folders` in combination to understand the codebase structure and history. 23 | - Structure tool calls logically, documenting the rationale before execution. 24 | - For complex tasks, break them down into smaller, manageable steps using tool calls. 25 | - When using `@Files` or `@Code`, specify the file path and relevant code sections clearly. 26 | - If a tool call fails, attempt to diagnose the issue using error messages and logs. Refer to the troubleshooting guides if needed: 27 | - @Common Issues 28 | - @Troubleshooting Guide 29 | - Follow consistent naming conventions (e.g., camelCase for variables, PascalCase for classes). 30 | - Use meaningful variable and function names. 31 | - Write clear and concise comments. 32 | - Break down complex functions into smaller, more manageable units. 33 | - Handle errors gracefully and provide informative error messages. 34 | - Write unit and integration tests for critical components. 35 | - Keep code DRY (Don't Repeat Yourself) by abstracting reusable logic into functions or modules. 36 | 37 | ## Constraints 38 | - You have a limited context window (Claude's limitation). 39 | - You can make up to 25 tool calls per turn in Agent Composer mode. 40 | - Adhere to the "Cursor AI Operating Instructions" provided separately. 41 | - Prioritize code quality, maintainability, and security. 42 | - Avoid making assumptions; ask clarifying questions when needed. 43 | 44 | ## Tokenization Settings 45 | - Estimated chars-per-token: 3.5 46 | - Max tokens for the AI: 120 0000 47 | - Plan for summary when **workflow-state.mdc** exceeds ~12 K chars. 48 | 49 | --- 50 | 51 | ## Changelog 52 | 53 | 54 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 🐛 Bug Report 3 | about: Create a report to help us improve the framework 4 | title: '[BUG] ' 5 | labels: ['bug', 'needs-triage'] 6 | assignees: '' 7 | --- 8 | 9 | ## 🐛 Bug Description 10 | 11 | **Clear and concise description of what the bug is.** 12 | 13 | ## 🔄 Steps to Reproduce 14 | 15 | 1. Go to '...' 16 | 2. Click on '....' 17 | 3. Scroll down to '....' 18 | 4. See error 19 | 20 | ## ✅ Expected Behavior 21 | 22 | **A clear and concise description of what you expected to happen.** 23 | 24 | ## ❌ Actual Behavior 25 | 26 | **A clear and concise description of what actually happened.** 27 | 28 | ## 📸 Screenshots 29 | 30 | **If applicable, add screenshots to help explain your problem.** 31 | 32 | ## 🖥️ Environment 33 | 34 | **Please complete the following information:** 35 | 36 | - **OS**: [e.g., macOS 13.0, Windows 11, Ubuntu 22.04] 37 | - **Cursor IDE Version**: [e.g., 0.42.0] 38 | - **Framework Version**: [e.g., 1.0.0] 39 | - **Node.js Version**: [e.g., 18.17.0] 40 | - **Project Type**: [e.g., React TypeScript, Node.js API, Monorepo] 41 | 42 | ## 📋 Rule Configuration 43 | 44 | **Please share relevant rule configuration:** 45 | 46 | ```yaml 47 | # Copy relevant sections from your .cursor/rules/ files 48 | # For example, from project-config.mdc: 49 | --- 50 | description: Your project configuration 51 | globs: "**/*.*" 52 | alwaysApply: true 53 | --- 54 | ``` 55 | 56 | ## 📝 Additional Context 57 | 58 | **Add any other context about the problem here.** 59 | 60 | - **Related Rules**: Which cursor rules are involved? 61 | - **File Patterns**: What file types are affected? 62 | - **Workflow Phase**: Which development phase (Blueprint/Construct/Validate)? 63 | - **Team Size**: Individual developer or team environment? 64 | 65 | ## 🔍 Error Logs 66 | 67 | **If applicable, include relevant error messages or logs:** 68 | 69 | ``` 70 | Paste error messages here 71 | ``` 72 | 73 | ## 🤔 Possible Solution 74 | 75 | **If you have ideas on how to fix this, please share them.** 76 | 77 | ## ✅ Checklist 78 | 79 | **Please check all that apply:** 80 | 81 | - [ ] I have searched existing issues to ensure this is not a duplicate 82 | - [ ] I have tested this with the latest version of the framework 83 | - [ ] I have included all relevant information (environment, configuration, etc.) 84 | - [ ] I have provided clear steps to reproduce the issue 85 | - [ ] I have included screenshots or error logs if applicable 86 | 87 | ## 🔗 Related Issues 88 | 89 | **Link any related issues here:** 90 | 91 | - #[issue number] 92 | 93 | --- 94 | 95 | **Thank you for taking the time to report this bug! 🙏** 96 | 97 | *The more information you provide, the faster we can help resolve the issue.* -------------------------------------------------------------------------------- /.cursor/rules/user-rules-template.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: 3 | globs: 4 | alwaysApply: false 5 | --- 6 | 7 | Act as an expert AI programming assistant who produces clear, idiomatic code that adheres to the project's standards (see ## Tech Stack and ## Critical Patterns & Conventions in .cursor/rules/project-config.mdc). Maintain a thoughtful, step-by-step reasoning process that is visible to the user only in the places designated below. 8 | 9 | General Guidelines 10 | Respect section boundaries. 11 | Every write-back must stay inside the correct ## block of .cursor/rules/workflow-state.mdc (## State, ## Plan, ## Rules, ## Items, ## Log, ## ArchiveLog). Never mix content between them. 12 | 13 | Keep logs and status updates concise; avoid narrative fluff. 14 | 15 | Workflow Phases 16 | 1 · BLUEPRINT (planning) 17 | - Before writing any implementation code, switch to the BLUEPRINT phase. 18 | - Always double check our .cursor/rules/architecture.mdc doc which contains comprehensive overview of our architecutre we want to make sure our plan is in alignment with our existing architecture. 19 | - You must always check our .cursor/rules/epics.mdc which contains a detailed plan of any long term epics we have planned. Make sure we track our progress in .cursor/rules/epics.mdc as we are completing our steps in this workflow. Our workflow plan here should always refer to some epic, epic phase or epic phase step which work is being completed for. 20 | - Blueprint plan should always be cross-referenced with our global cursor rule .cursor/rules/rules.mdc , all the rules defined there must be followed. 21 | - Think step-by-step: draft a very detailed plan in the ## Plan section using pseudocode or clear action descriptions. Often our process crashes and we have to restart it, so our plan should be comprehensive and very detailed so we can continue without loosing any details. Make sure that each step is not too large. Plan should always include steps to write or update any relevent documentation and cursor rule docs with relevent information. 22 | - When the plan is ready, set State.Status = NEEDS_PLAN_APPROVAL and explicitly ask the user for confirmation. 23 | 24 | 2 · CONSTRUCT (implementation) 25 | - Adhere strictly to the approved plan. 26 | - Produce code that is correct, secure, performant, and idiomatic. We want modular architecture that is highly re-usable. 27 | - When implementing architectural changes, update .cursor/rules/architecture.mdc with new patterns, decisions, or design choices. 28 | - Prioritise readability over premature optimisation. Prioritise code quality over time to write the code. We don't mind taking extra time to write quality code. 29 | - Leave no TODOs, placeholders, or incomplete stubs. Never leave any issues broken or not fixed. 30 | - Include all imports/dependencies and use conventional naming. 31 | - Run tests/linters after each atomic change; log the results. 32 | 33 | 3 · VALIDATE (final checks) 34 | - Re-run the full test suite and any E2E checks. 35 | - On success, set Phase = VALIDATE, Status = COMPLETED. 36 | - Automatically trigger post-processing rules (see below). 37 | 38 | Automatic House-Keeping Rules 39 | Rule Trigger Action 40 | RULE_LOG_ROTATE_01 length(## Log) > 5 000 chars Summarise the five most important points from ## Log into ## ArchiveLog, then clear ## Log. 41 | RULE_SUMMARY_01 Phase == VALIDATE && Status == COMPLETED Prepend a one-sentence summary as a new list item under ## Changelog in project_config.md. 42 | 43 | Construct-Phase Coding Checklist 44 | ✅ Follow the approved plan exactly. 45 | ✅ Generate up-to-date, bug-free, fully functional code. 46 | ✅ Run and pass all tests/linters. 47 | ✅ Do not leak secrets; mask any credentials before logging. 48 | ✅ Confirm each step's completion in ## Log (briefly). 49 | 50 | Stay disciplined: plan → seek approval → implement → validate → summarise → iterate. 51 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. 6 | 7 | ## Our Standards 8 | 9 | Examples of behavior that contributes to creating a positive environment include: 10 | 11 | * Using welcoming and inclusive language 12 | * Being respectful of differing viewpoints and experiences 13 | * Gracefully accepting constructive criticism 14 | * Focusing on what is best for the community 15 | * Showing empathy towards other community members 16 | * Sharing knowledge and helping others learn 17 | * Recognizing and appreciating contributions from all community members 18 | 19 | Examples of unacceptable behavior by participants include: 20 | 21 | * The use of sexualized language or imagery and unwelcome sexual attention or advances 22 | * Trolling, insulting/derogatory comments, and personal or political attacks 23 | * Public or private harassment 24 | * Publishing others' private information, such as a physical or electronic address, without explicit permission 25 | * Other conduct which could reasonably be considered inappropriate in a professional setting 26 | 27 | ## Cursor AI Development Standards 28 | 29 | As this project specifically deals with AI-assisted development, we also expect: 30 | 31 | * **Responsible AI Usage**: Share AI-generated code responsibly and ensure proper attribution 32 | * **Knowledge Sharing**: Help others understand how to effectively work with AI tools 33 | * **Ethical Considerations**: Consider the implications of AI-assisted development on the broader community 34 | * **Quality Focus**: Maintain high standards for AI-generated contributions 35 | 36 | ## Our Responsibilities 37 | 38 | Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. 39 | 40 | Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. 41 | 42 | ## Scope 43 | 44 | This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. 45 | 46 | ## Enforcement 47 | 48 | Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [conduct@your-email.com]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. 49 | 50 | Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. 51 | 52 | ## Attribution 53 | 54 | This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html 55 | 56 | For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/release-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: 🚀 Release Request 3 | about: Request a new release of the Cursor Rule Framework 4 | title: 'Release Request: v[VERSION] - [BRIEF_DESCRIPTION]' 5 | labels: ['release', 'enhancement'] 6 | assignees: ['fbrbovic'] 7 | --- 8 | 9 | ## 📋 Release Information 10 | 11 | **Requested Release Type:** 12 | - [ ] 🐛 Patch (bug fixes, documentation updates) 13 | - [ ] ✨ Minor (new features, backward compatible) 14 | - [ ] 💥 Major (breaking changes, new architecture) 15 | - [ ] 🧪 Prerelease (alpha/beta/rc) 16 | 17 | **Requested Version:** `v[X.Y.Z]` 18 | 19 | **Target Release Date:** YYYY-MM-DD (if applicable) 20 | 21 | ## 🎯 Release Rationale 22 | 23 | **Why is this release needed?** 24 | 25 | 26 | **Key Changes Since Last Release:** 27 | 28 | - 29 | - 30 | - 31 | 32 | **Breaking Changes (if any):** 33 | 34 | - 35 | - 36 | 37 | ## 📦 Release Content 38 | 39 | **New Features:** 40 | 41 | - 42 | - 43 | 44 | **Bug Fixes:** 45 | 46 | - 47 | - 48 | 49 | **Documentation Updates:** 50 | 51 | - 52 | - 53 | 54 | **Examples/Templates:** 55 | 56 | - 57 | - 58 | 59 | ## 🧪 Testing Status 60 | 61 | **Manual Testing Completed:** 62 | - [ ] Rule validation works correctly 63 | - [ ] Documentation links are functional 64 | - [ ] Examples run without errors 65 | - [ ] Installation instructions are accurate 66 | 67 | **Validation Scripts:** 68 | - [ ] `npm run validate:rules` passes 69 | - [ ] `npm run validate:docs` passes 70 | - [ ] No linting errors 71 | 72 | **Cross-Platform Testing:** 73 | - [ ] Windows 74 | - [ ] macOS 75 | - [ ] Linux 76 | 77 | ## 📚 Documentation Updates 78 | 79 | **Updated Files:** 80 | - [ ] README.md 81 | - [ ] CHANGELOG.md (Unreleased section) 82 | - [ ] Release documentation 83 | - [ ] Migration guides (if needed) 84 | 85 | **Links Verified:** 86 | - [ ] All internal links work 87 | - [ ] External links are functional 88 | - [ ] Examples are accessible 89 | 90 | ## 🎖️ Contributors 91 | 92 | **Contributors to Include in Release Notes:** 93 | 94 | - @username - Feature/fix description 95 | - @username - Feature/fix description 96 | 97 | ## 📋 Pre-Release Checklist 98 | 99 | Before requesting approval, ensure: 100 | 101 | **Code Quality:** 102 | - [ ] All changes are committed and pushed 103 | - [ ] No merge conflicts with main branch 104 | - [ ] Code follows project standards 105 | 106 | **Documentation:** 107 | - [ ] Changelog is updated in Unreleased section 108 | - [ ] README reflects all new features 109 | - [ ] Migration guides provided for breaking changes 110 | - [ ] All new features are documented 111 | 112 | **Testing:** 113 | - [ ] Manual testing completed 114 | - [ ] Validation scripts pass 115 | - [ ] Examples work correctly 116 | - [ ] Installation tested from scratch 117 | 118 | **Release Notes:** 119 | - [ ] Clear description of changes 120 | - [ ] Breaking changes highlighted 121 | - [ ] Known issues documented 122 | - [ ] Acknowledgments included 123 | 124 | ## 🔄 Post-Release Tasks 125 | 126 | **After Release:** 127 | - [ ] Verify release assets are correct 128 | - [ ] Test download and installation 129 | - [ ] Update any external documentation 130 | - [ ] Announce in discussions/community channels 131 | 132 | ## 💬 Additional Context 133 | 134 | **Special Considerations:** 135 | 136 | 137 | **Community Impact:** 138 | 139 | 140 | **Dependencies:** 141 | 142 | 143 | --- 144 | 145 | **For Maintainers:** 146 | 147 | **Release Approval:** 148 | - [ ] Changes reviewed and approved 149 | - [ ] Pre-release checklist completed 150 | - [ ] Release notes prepared 151 | - [ ] Ready to trigger release workflow 152 | 153 | **Release Process:** 154 | 1. [ ] Trigger release via GitHub Actions 155 | 2. [ ] Verify release assets 156 | 3. [ ] Update CHANGELOG.md post-release 157 | 4. [ ] Close this issue 158 | 5. [ ] Announce release 159 | 160 | --- 161 | 162 | /cc @fbrbovic -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # 📚 Cursor Rule Framework Documentation 2 | 3 | Welcome to the comprehensive documentation for the Cursor Rule Framework! This guide will help you master AI-assisted development with structured cursor rules. 4 | 5 | ## 🎯 Getting Started 6 | 7 | New to the framework? Start here: 8 | 9 | 1. **[Quick Start Guide](../README.md#-quick-start)** - Get up and running in 5 minutes 10 | - ⚠️ **CRITICAL**: Install `user-rules-template.mdc` in Cursor IDE User Rules 11 | 2. **[Core Concepts](#-core-concepts)** - Understand the fundamental principles 12 | 3. **[Your First Rule](custom-rules.md#creating-your-first-rule)** - Create a custom rule 13 | 4. **[Workflow Basics](workflow-system.md#basic-workflow)** - Learn the three-phase development process 14 | 15 | ## 📖 Core Concepts 16 | 17 | ### Essential Guides 18 | - **[Rule Organization](rule-organization.md)** - How rules are structured and managed 19 | - Rule hierarchy and scope 20 | - MDC metadata format 21 | - **The Master Rule Registry (`rules.mdc`)** - Dynamic rule accumulation 22 | - Location policies and best practices 23 | 24 | - **[Workflow System](workflow-system.md)** - AI-driven development with epic and architecture integration 25 | - Phase-by-phase development with automatic architecture validation 26 | - Quality gates and validation with architectural consistency 27 | - State management and tracking with epic progress updates 28 | 29 | - **[Epic Planning](epic-planning.md)** - Managing large initiatives with AI 30 | - Epic → Phase → Step hierarchy with architecture impact assessment 31 | - AI-assisted planning techniques with automatic architecture integration 32 | - Progress tracking and validation with workflow system integration 33 | 34 | ## 🛠️ Development Guides 35 | 36 | ### Rule Development 37 | - **[Custom Rules](custom-rules.md)** - Creating domain-specific rules 38 | - **[Rule Testing](rule-testing.md)** - Validating rule effectiveness 39 | - **[Rule Templates](rule-templates.md)** - Copy-paste rule examples 40 | 41 | ### Team Workflows 42 | - **[Team Integration](team-integration.md)** - Multi-developer workflows 43 | - **[Best Practices](best-practices.md)** - Proven patterns for success 44 | 45 | ### Architecture & Design 46 | - **[Architecture Patterns](architecture-patterns.md)** - Scalable system design 47 | - **[Migration Guide](migration-guide.md)** - Adopting the framework in existing projects 48 | 49 | ## 📋 Reference Documentation 50 | 51 | ### Technical Reference 52 | - **[MDC Format Specification](mdc-format-specification.md)** - Complete MDC format reference 53 | - **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions 54 | - **[FAQ](faq.md)** - Frequently asked questions 55 | 56 | ### Examples & Templates 57 | - **[Example Projects](../examples/README.md)** - Real-world usage examples 58 | - **[Rule Templates](rule-templates.md)** - Copy-paste rule examples 59 | 60 | ## 🎓 Learning Resources 61 | 62 | ### By Role 63 | - **[For Developers](for-developers.md)** - Individual developer workflows 64 | - **[For Teams](for-teams.md)** - Team collaboration patterns 65 | - **[For Architects](for-architects.md)** - System design and architecture 66 | 67 | ## 🆘 Support & Troubleshooting 68 | 69 | ### Getting Help 70 | - **[Troubleshooting Guide](troubleshooting.md)** - Common issues and solutions 71 | - **[FAQ](faq.md)** - Frequently asked questions 72 | 73 | ### Contributing 74 | - **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute to the project 75 | 76 | ## 💡 Tips for Success 77 | 78 | 1. **Start Small**: Begin with simple rules and gradually add complexity 79 | 2. **Iterate Often**: Use the AI-driven workflow system to maintain quality 80 | 3. **Share Knowledge**: Document your patterns for team reuse 81 | 4. **Stay Organized**: Follow the location and naming conventions 82 | 5. **Test Thoroughly**: Validate rules in real projects before sharing 83 | 84 | ## 📞 Need Help? 85 | 86 | - **🐛 Bug Reports**: [GitHub Issues](https://github.com/fbrbovic/cursor-rule-framework/issues) 87 | - **💬 Discussions**: [GitHub Discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions) 88 | - **📖 Wiki**: [Community Wiki](https://github.com/fbrbovic/cursor-rule-framework/wiki) 89 | 90 | --- 91 | 92 | **Ready to dive in?** Start with the [Quick Start Guide](../README.md#-quick-start) or explore the [Core Concepts](#-core-concepts) above! 93 | 94 | *This documentation is continuously updated. Last updated: January 20, 2025* -------------------------------------------------------------------------------- /.github/release-template.md: -------------------------------------------------------------------------------- 1 | # 🎯 Cursor Rule Framework v{VERSION} 2 | 3 | > **Release Date**: {DATE} 4 | > **Release Type**: {TYPE} (Major/Minor/Patch/Prerelease) 5 | 6 | ## 📋 Overview 7 | 8 | Brief description of this release and its key highlights. 9 | 10 | ## ✨ What's New 11 | 12 | ### 🎯 Key Features 13 | - **Feature Name**: Description of the new feature 14 | - **Enhancement**: Description of improvements 15 | 16 | ### 🔧 Improvements 17 | - **Performance**: Specific performance improvements 18 | - **Developer Experience**: UX/DX enhancements 19 | - **Documentation**: Documentation updates 20 | 21 | ### 🐛 Bug Fixes 22 | - **Fix Description**: What was fixed and why 23 | - **Issue Resolution**: Reference to resolved issues 24 | 25 | ### 🔒 Security 26 | - **Security Enhancement**: Any security-related changes 27 | - **Vulnerability Fixes**: CVE fixes if applicable 28 | 29 | ## 📦 Release Assets 30 | 31 | This release includes the following downloadable assets: 32 | 33 | - **`cursor-rule-framework-v{VERSION}.tar.gz`** - Complete framework bundle with all documentation and examples 34 | - **`quick-start-v{VERSION}.tar.gz`** - Essential rules only for quick setup 35 | - **`checksums.txt`** - SHA256 checksums for all assets 36 | 37 | ## 🚀 Getting Started 38 | 39 | ### New Users 40 | ```bash 41 | # Download and extract the framework 42 | curl -L https://github.com/fbrbovic/cursor-rule-framework/releases/download/v{VERSION}/cursor-rule-framework-v{VERSION}.tar.gz | tar -xz 43 | 44 | # Or use the quick-start bundle 45 | curl -L https://github.com/fbrbovic/cursor-rule-framework/releases/download/v{VERSION}/quick-start-v{VERSION}.tar.gz | tar -xz 46 | ``` 47 | 48 | ### Existing Users 49 | ```bash 50 | # Update your existing installation 51 | git fetch --tags 52 | git checkout v{VERSION} 53 | 54 | # Or download the latest rules 55 | curl -L https://github.com/fbrbovic/cursor-rule-framework/releases/download/v{VERSION}/quick-start-v{VERSION}.tar.gz | tar -xz 56 | ``` 57 | 58 | ## 🔄 Migration Guide 59 | 60 | ### Breaking Changes (if any) 61 | - **Change Description**: What changed and how to adapt 62 | - **Migration Steps**: Step-by-step migration instructions 63 | 64 | ### Deprecated Features 65 | - **Feature Name**: What's deprecated and when it will be removed 66 | - **Alternative**: Recommended alternative approach 67 | 68 | ## 📚 Documentation 69 | 70 | - **[Complete Documentation](../docs/README.md)** - Full framework documentation 71 | - **[Quick Start Guide](../README.md#-quick-start)** - Get started in 5 minutes 72 | - **[Migration Guide](../docs/migration-guide.md)** - Upgrade from previous versions 73 | - **[Changelog](../CHANGELOG.md)** - Detailed change history 74 | 75 | ## 🐛 Known Issues 76 | 77 | ### Current Limitations 78 | - **Issue Description**: Known issues and workarounds 79 | - **Planned Fix**: When the issue will be addressed 80 | 81 | ### Compatibility 82 | - **Cursor IDE**: Minimum version requirements 83 | - **Operating Systems**: Supported platforms 84 | - **Dependencies**: Required dependencies 85 | 86 | ## 💬 Community & Support 87 | 88 | ### Getting Help 89 | - **[GitHub Discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions)** - Community questions and discussions 90 | - **[Issues](https://github.com/fbrbovic/cursor-rule-framework/issues)** - Bug reports and feature requests 91 | - **[Documentation](https://github.com/fbrbovic/cursor-rule-framework/wiki)** - Comprehensive guides 92 | 93 | ### Contributing 94 | - **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute 95 | - **[Development Setup](../docs/development.md)** - Set up development environment 96 | - **[Code of Conduct](../CODE_OF_CONDUCT.md)** - Community guidelines 97 | 98 | ## 🙏 Acknowledgments 99 | 100 | ### Contributors 101 | Special thanks to everyone who contributed to this release: 102 | - **@username** - Contribution description 103 | - **@username** - Contribution description 104 | 105 | ### Community 106 | Thanks to the community members who provided feedback, reported issues, and shared their experiences. 107 | 108 | ## 📈 Release Statistics 109 | 110 | - **Files Changed**: X files 111 | - **Lines Added**: +X lines 112 | - **Lines Removed**: -X lines 113 | - **Contributors**: X contributors 114 | - **Issues Closed**: X issues 115 | - **Pull Requests Merged**: X PRs 116 | 117 | ## 🔗 Links 118 | 119 | - **[Download Latest](https://github.com/fbrbovic/cursor-rule-framework/releases/latest)** 120 | - **[All Releases](https://github.com/fbrbovic/cursor-rule-framework/releases)** 121 | - **[Repository](https://github.com/fbrbovic/cursor-rule-framework)** 122 | - **[Documentation](../docs/README.md)** 123 | 124 | --- 125 | 126 | **Built with ❤️ for the Cursor AI community** 127 | 128 | *Questions? Join our [discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions) or check the [documentation](../docs/README.md)!* -------------------------------------------------------------------------------- /RELEASE_SYSTEM.md: -------------------------------------------------------------------------------- 1 | # 🚀 Release System Quick Reference 2 | 3 | > **Professional GitHub Release System for the Cursor Rule Framework** 4 | 5 | ## 🎯 What's Included 6 | 7 | ✅ **Automated Release Workflow** - GitHub Actions for seamless releases 8 | ✅ **Semantic Versioning** - SemVer with conventional commits 9 | ✅ **AI-Safe Releases** - Smart detection + prevents accidental major releases 10 | ✅ **Quality Gates** - Validation before every release 11 | ✅ **Release Assets** - Downloadable bundles for users 12 | ✅ **Changelog Automation** - Auto-generated release notes 13 | ✅ **Multiple Release Types** - Patch, minor, major, prerelease 14 | ✅ **Validation Scripts** - Rule and documentation validation 15 | ✅ **Release Templates** - Consistent release formatting 16 | ✅ **Issue Templates** - Streamlined release requests 17 | 18 | ## 🚀 Quick Start for Maintainers 19 | 20 | ### Automatic Release (Recommended) 21 | ```bash 22 | # Conventional commits (preferred) 23 | git commit -m "feat: add new validation rules" # → Minor release 24 | git commit -m "fix: resolve parsing issue" # → Patch release 25 | 26 | # Smart detection works even without conventional format! 27 | git commit -m "Add new rule template" # → Minor (smart detection) 28 | git commit -m "Update documentation" # → Patch (smart detection) 29 | git commit -m "Fix validation bug" # → Patch (smart detection) 30 | 31 | # Note: Major releases require manual trigger for AI safety 32 | git push origin main 33 | ``` 34 | 35 | ### Manual Release 36 | ```bash 37 | # GitHub Actions UI 38 | Actions → Release → Run workflow → Select type → Run 39 | 40 | # Command line 41 | npm run release:patch # Bug fixes 42 | npm run release:minor # New features 43 | npm run release:major # Breaking changes 44 | ``` 45 | 46 | ## 🔍 Quality Checks 47 | 48 | ```bash 49 | # Validate before releasing 50 | npm run validate:rules # Check cursor rule format 51 | npm run validate:docs # Check documentation quality 52 | npm test # Run test suite 53 | npm run lint # Check code style 54 | ``` 55 | 56 | ## 📦 What Users Get 57 | 58 | Each release automatically creates: 59 | - **Complete Framework Bundle** (`cursor-rule-framework-v1.2.3.tar.gz`) 60 | - **Quick-Start Bundle** (`quick-start-v1.2.3.tar.gz`) 61 | - **Checksums** (`checksums.txt`) 62 | - **Release Notes** (auto-generated from commits) 63 | 64 | ## 🏷️ Version Strategy 65 | 66 | | Commit Type | Version Bump | Example | 67 | |-------------|--------------|---------| 68 | | `fix:` | Patch | `1.0.0` → `1.0.1` | 69 | | `feat:` | Minor | `1.0.0` → `1.1.0` | 70 | | Manual trigger only | Major | `1.0.0` → `2.0.0` | 71 | 72 | ## 📋 Pre-Release Checklist 73 | 74 | - [ ] All validation scripts pass 75 | - [ ] Documentation is up to date 76 | - [ ] Examples work correctly 77 | - [ ] CHANGELOG.md Unreleased section is populated 78 | - [ ] No broken links in documentation 79 | - [ ] Test installation from scratch 80 | 81 | ## 🛠️ Files Created 82 | 83 | ``` 84 | 📁 .github/ 85 | ├── workflows/release.yml # Main release automation 86 | ├── release-template.md # Release notes template 87 | └── ISSUE_TEMPLATE/release-request.md # Release request template 88 | 89 | 📁 scripts/ 90 | ├── validate-rules.js # Cursor rule validation 91 | └── validate-docs.js # Documentation validation 92 | 93 | 📄 package.json # Version management & scripts 94 | 📄 docs/release-management.md # Complete documentation 95 | 📄 RELEASE_SYSTEM.md # This quick reference 96 | ``` 97 | 98 | ## 🎭 For Contributors 99 | 100 | ### Request a Release 101 | 1. Create issue using **Release Request** template 102 | 2. Fill out the comprehensive checklist 103 | 3. Tag maintainers for review 104 | 105 | ### Trigger Automatic Release 106 | 1. Use conventional commit messages 107 | 2. Push to `main` branch 108 | 3. Release triggers automatically 109 | 110 | ## 🔧 Troubleshooting 111 | 112 | ### Common Issues 113 | - **Workflow fails**: Check validation scripts 114 | - **Missing assets**: Re-run workflow 115 | - **Wrong version**: Delete tag and retry 116 | 117 | ### Recovery 118 | ```bash 119 | # Fix failed release 120 | git tag -d v1.2.3 # Delete local tag 121 | git push origin :v1.2.3 # Delete remote tag 122 | # Fix issue and re-run workflow 123 | ``` 124 | 125 | ## 📚 Documentation 126 | 127 | - **[Complete Guide](docs/release-management.md)** - Detailed release documentation 128 | - **[AI-Safe Commits](docs/ai-safe-commits.md)** - Working safely with Cursor AI 129 | - **[Contributing](CONTRIBUTING.md)** - How to contribute 130 | - **[Changelog](CHANGELOG.md)** - Version history 131 | 132 | ## 🎉 Ready to Release? 133 | 134 | The system is production-ready! Start using conventional commits or trigger a manual release to see it in action. 135 | 136 | --- 137 | 138 | **Questions?** Check the [complete documentation](docs/release-management.md) or create an [issue](https://github.com/fbrbovic/cursor-rule-framework/issues)! -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | # 🚀 Pull Request 2 | 3 | ## 📋 Summary 4 | 5 | **Briefly describe what this PR accomplishes and why it's needed.** 6 | 7 | ## 🔄 Type of Change 8 | 9 | **Please select the type of change this PR introduces:** 10 | 11 | - [ ] 🐛 **Bug fix** (non-breaking change which fixes an issue) 12 | - [ ] ✨ **New feature** (non-breaking change which adds functionality) 13 | - [ ] 📖 **Documentation update** (improves or adds documentation) 14 | - [ ] 🔧 **Rule improvement** (enhances existing cursor rules) 15 | - [ ] 🎯 **New rule** (adds new cursor rule for specific domain/pattern) 16 | - [ ] 🏗️ **Framework enhancement** (improves core framework functionality) 17 | - [ ] 🧪 **Example addition** (adds new example project) 18 | - [ ] 💥 **Breaking change** (fix or feature that would cause existing functionality to not work as expected) 19 | 20 | ## 🎯 Changes Made 21 | 22 | **List the specific changes made in this PR:** 23 | 24 | - Change 1: Description 25 | - Change 2: Description 26 | - Change 3: Description 27 | 28 | ## 📁 Files Changed 29 | 30 | **Highlight the key files that were modified:** 31 | 32 | ### Core Framework 33 | - [ ] `.cursor/rules/cursor-rules-management.mdc` 34 | - [ ] `.cursor/rules/project-config.mdc` 35 | - [ ] `.cursor/rules/workflow-state.mdc` 36 | - [ ] `.cursor/rules/epics.mdc` 37 | 38 | ### Documentation 39 | - [ ] `README.md` 40 | - [ ] `docs/` 41 | - [ ] `CONTRIBUTING.md` 42 | - [ ] `CHANGELOG.md` 43 | 44 | ### Examples 45 | - [ ] `examples/` 46 | - [ ] Example-specific rules 47 | - [ ] Example documentation 48 | 49 | ### Other 50 | - [ ] `.github/` templates 51 | - [ ] Configuration files 52 | - [ ] Other: _specify_ 53 | 54 | ## 🧪 Testing 55 | 56 | **Describe how you tested these changes:** 57 | 58 | ### Manual Testing 59 | - [ ] **Cursor IDE Integration**: Verified rules load correctly in Cursor 60 | - [ ] **Rule Application**: Tested rules apply to correct file patterns 61 | - [ ] **Workflow Testing**: Validated development workflow phases 62 | - [ ] **Example Testing**: Verified example projects work correctly 63 | 64 | ### Automated Testing 65 | - [ ] **Rule Validation**: Metadata format and structure validated 66 | - [ ] **Documentation**: Links and references verified 67 | - [ ] **Code Quality**: ESLint/Prettier checks passed 68 | - [ ] **Integration**: No conflicts with existing rules 69 | 70 | ### Testing Checklist 71 | - [ ] Rules appear in Cursor's rule picker 72 | - [ ] Glob patterns match intended files 73 | - [ ] No metadata errors or warnings 74 | - [ ] Examples build and run successfully 75 | - [ ] Documentation renders correctly 76 | 77 | ## 📖 Documentation 78 | 79 | **How does this change affect documentation?** 80 | 81 | - [ ] **No documentation needed** (internal change, bug fix, etc.) 82 | - [ ] **Documentation updated** (included in this PR) 83 | - [ ] **Documentation needed** (follow-up PR required) 84 | 85 | **If documentation was updated, describe what was changed:** 86 | 87 | ## 🔗 Related Issues 88 | 89 | **Link any related issues, discussions, or pull requests:** 90 | 91 | - Closes #[issue number] 92 | - Related to #[issue number] 93 | - Depends on #[PR number] 94 | 95 | ## 💡 Implementation Notes 96 | 97 | **Provide any additional context about implementation decisions:** 98 | 99 | ### Design Decisions 100 | - **Why this approach**: Explanation of chosen solution 101 | - **Alternatives considered**: Other approaches that were evaluated 102 | - **Trade-offs**: Benefits and limitations of this implementation 103 | 104 | ### Rule-Specific Notes 105 | **If this PR adds or modifies rules:** 106 | 107 | - **Rule Scope**: Global, domain-specific, or feature-specific 108 | - **File Patterns**: What files this rule targets 109 | - **Integration**: How it works with existing rules 110 | - **Usage**: When and how developers should use this rule 111 | 112 | ## 🚨 Breaking Changes 113 | 114 | **If this is a breaking change, describe:** 115 | 116 | - **What breaks**: Specific functionality that will no longer work 117 | - **Migration path**: How users can update their existing setups 118 | - **Timeline**: When this change will be released 119 | 120 | ## 📸 Screenshots 121 | 122 | **If applicable, add screenshots to demonstrate the changes:** 123 | 124 | ### Before 125 | [Screenshot or description of old behavior] 126 | 127 | ### After 128 | [Screenshot or description of new behavior] 129 | 130 | ## ✅ Checklist 131 | 132 | **Please check all items that apply:** 133 | 134 | ### Code Quality 135 | - [ ] Code follows the project's style guidelines 136 | - [ ] Self-review of code completed 137 | - [ ] Code is properly commented 138 | - [ ] No unnecessary console.logs or debug code 139 | 140 | ### Rule Quality (if applicable) 141 | - [ ] Rule has proper MDC metadata 142 | - [ ] Glob patterns are specific and tested 143 | - [ ] Rule content follows template structure 144 | - [ ] Examples are included and functional 145 | - [ ] No conflicts with existing rules 146 | 147 | ### Documentation 148 | - [ ] Documentation updated (if needed) 149 | - [ ] Examples updated (if needed) 150 | - [ ] Changelog updated (if needed) 151 | - [ ] README updated (if needed) 152 | 153 | ### Testing 154 | - [ ] All tests pass locally 155 | - [ ] New tests added for new functionality 156 | - [ ] Manual testing completed 157 | - [ ] No breaking changes (or documented) 158 | 159 | ### Process 160 | - [ ] PR title follows conventional commit format 161 | - [ ] Labels added appropriately 162 | - [ ] Assignees and reviewers added 163 | - [ ] Linked to relevant issues 164 | 165 | ## 🎯 Post-Merge Tasks 166 | 167 | **Tasks to complete after this PR is merged:** 168 | 169 | - [ ] Update related documentation 170 | - [ ] Announce changes to community 171 | - [ ] Create follow-up issues 172 | - [ ] Update examples or tutorials 173 | 174 | ## 💬 Additional Notes 175 | 176 | **Any additional information, concerns, or questions:** 177 | 178 | --- 179 | 180 | ## 📞 Reviewer Notes 181 | 182 | **For reviewers, please verify:** 183 | 184 | - [ ] **Functionality**: Changes work as described 185 | - [ ] **Code Quality**: Meets project standards 186 | - [ ] **Documentation**: Adequate and accurate 187 | - [ ] **Testing**: Properly tested and validated 188 | - [ ] **Integration**: No conflicts with existing code 189 | - [ ] **User Experience**: Improves developer experience 190 | 191 | --- 192 | 193 | **Thank you for contributing to the Cursor Rule Framework! 🙏** 194 | 195 | *Your contribution helps make AI-assisted development better for everyone.* -------------------------------------------------------------------------------- /.cursor/rules/cursor-rules-management.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: Comprehensive cursor rules management including location policy and metadata preservation. Used anytime new cursor AI rule is to be generated or if existing one is updated. 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # 🚨 CRITICAL: Cursor Rules Management Policy 🚨 7 | 8 | This rule ensures proper location, format, and handling of all Cursor MDC rule files. 9 | 10 | ## PART 1: MANDATORY LOCATION POLICY 11 | 12 | ### All Cursor Rules Must Live in `.cursor/rules/` 13 | 14 | **This is the ONLY acceptable location for cursor rules files (.mdc).** 15 | 16 | #### ✅ Correct Locations 17 | - ✅ `.cursor/rules/rules.mdc` 18 | - ✅ `.cursor/rules/architecture.mdc` 19 | - ✅ `.cursor/rules/any-other-rule.mdc` 20 | 21 | #### ❌ INCORRECT Locations (NEVER USE) 22 | - ❌ `rules.mdc` (root level) 23 | - ❌ `migration.mdc` (root level) 24 | - ❌ `backend-encore/rules.mdc` 25 | - ❌ Any other location outside `.cursor/rules/` 26 | 27 | #### Why Location Matters 28 | 1. **Cursor IDE Integration**: Cursor only recognizes rules in `.cursor/rules/` 29 | 2. **Team Consistency**: All team members expect rules in standard location 30 | 3. **Version Control**: Proper .gitignore handling for cursor-specific files 31 | 4. **Tool Compatibility**: Other cursor-compatible tools expect this structure 32 | 33 | ## PART 2: MANDATORY MDC METADATA FORMAT 34 | 35 | ### What is MDC Metadata? 36 | Every `.mdc` file in the `.cursor/rules/` directory must have metadata at the top in this format: 37 | 38 | ``` 39 | --- 40 | description: Brief description of what this rule does 41 | globs: file/pattern/to/match/**/*.* 42 | alwaysApply: true/false 43 | --- 44 | 45 | # Rule content starts here 46 | ``` 47 | 48 | ### ABSOLUTE REQUIREMENTS 49 | 50 | #### 1. Never Remove or Modify Delimiters 51 | - The `---` lines at the beginning and end of metadata are CRITICAL 52 | - Removing these breaks the MDC format and disables the rule 53 | - Always preserve exactly three dashes on each line 54 | 55 | #### 2. Always Preserve Existing Fields 56 | When updating an MDC file, you MUST preserve: 57 | - `description`: Brief description of the rule's purpose 58 | - `globs`: File patterns that trigger this rule 59 | - `alwaysApply`: Whether rule applies to all contexts (true/false) 60 | 61 | #### 3. Only Update Content Below Metadata 62 | - Only modify content below the second `---` line 63 | - Never modify anything between the first and second `---` lines 64 | - If you need to change metadata fields, do so carefully and preserve the format 65 | 66 | ## PART 3: AI ASSISTANT WORKFLOW 67 | 68 | ### Before Creating/Editing Rules 69 | 1. **ALWAYS** check if `.cursor/rules/` directory exists 70 | 2. If it doesn't exist, create it first 71 | 3. **ALWAYS** create rules in `.cursor/rules/filename.mdc` 72 | 4. **ALWAYS** start with proper MDC metadata 73 | 5. Choose appropriate `globs` pattern for the rule's scope 74 | 6. Use `alwaysApply: true` only for workspace-wide rules 75 | 76 | ### Before Deleting Root-Level Rules 77 | 1. **ALWAYS** compare root-level rules with `.cursor/rules/` versions 78 | 2. Merge any new content from root-level to `.cursor/rules/` 79 | 3. Only delete root-level after confirming merge is complete 80 | 81 | ### When Updating Existing Rules 82 | 1. Read the entire file first to understand current metadata 83 | 2. Preserve existing metadata exactly as-is 84 | 3. Only modify content below the second `---` line 85 | 4. Test the rule still works after updating 86 | 87 | ## PART 4: COMMON MDC FILE TYPES AND METADATA 88 | 89 | ### Architecture Rules 90 | ``` 91 | --- 92 | description: Backend architecture guidelines and service structure 93 | globs: backend-encore/**/*.* 94 | alwaysApply: true 95 | --- 96 | ``` 97 | 98 | ### Service-Specific Rules 99 | ``` 100 | --- 101 | description: Rules for specific service or integration 102 | globs: backend-encore/service-name/**/*.* 103 | alwaysApply: false 104 | --- 105 | ``` 106 | 107 | ### Testing Rules 108 | ``` 109 | --- 110 | description: Testing patterns and requirements 111 | globs: **/*.test.ts, **/*.spec.ts 112 | alwaysApply: false 113 | --- 114 | ``` 115 | 116 | ### Global Workspace Rules 117 | ``` 118 | --- 119 | description: Rules applying to entire workspace 120 | globs: **/*.* 121 | alwaysApply: true 122 | --- 123 | ``` 124 | 125 | ## PART 5: ERROR DETECTION AND RECOVERY 126 | 127 | ### Symptoms of Broken MDC Files 128 | - Rule doesn't appear in Cursor's rule picker 129 | - Rule doesn't automatically apply when expected 130 | - File patterns don't match correctly 131 | - Rule appears as "invalid" in Cursor settings 132 | 133 | ### Recovery Process 134 | 1. Check for missing or malformed `---` delimiters 135 | 2. Verify all required fields are present 136 | 3. Ensure proper YAML format in metadata section 137 | 4. Verify file is in `.cursor/rules/` directory 138 | 5. Test rule functionality after fixing 139 | 140 | ## PART 6: VALIDATION CHECKLIST 141 | 142 | Before saving any MDC file, verify: 143 | - [ ] File is saved in `.cursor/rules/` directory 144 | - [ ] Metadata section starts and ends with `---` 145 | - [ ] All required fields are present and properly formatted 146 | - [ ] `globs` pattern matches intended files 147 | - [ ] `alwaysApply` setting is appropriate 148 | - [ ] Content below metadata follows proper markdown format 149 | - [ ] No duplicate rules files in root or other locations 150 | 151 | ## PART 7: COMMON MISTAKES TO AVOID 152 | 153 | ### Location Mistakes 154 | - Placing MDC files outside `.cursor/rules/` directory 155 | - Creating duplicate rules in multiple locations 156 | - Not checking for existing `.cursor/rules/` directory 157 | 158 | ### Format Mistakes 159 | - Removing metadata when updating content 160 | - Changing `globs` patterns without understanding implications 161 | - Using incorrect YAML syntax in metadata 162 | - Mixing content with metadata section 163 | 164 | ### Memory Reminder for AI Assistant 165 | - **Never** create rules files outside `.cursor/rules/` 166 | - **Always** use the full path: `.cursor/rules/filename.mdc` 167 | - **Always** preserve existing metadata exactly 168 | - **Always** check for content differences before deleting duplicates 169 | 170 | ## PART 8: DEBUGGING TIPS 171 | 172 | - Use Cursor's rule management interface to validate MDC files 173 | - Check Cursor settings to see if rules are properly loaded 174 | - Test rule application by matching against expected file patterns 175 | - Verify rule behavior in different contexts (auto-apply vs manual) 176 | 177 | --- 178 | 179 | **This rule was created to prevent repeated mistakes with cursor rules location and format. All requirements must be followed exactly.** 180 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to the Cursor Rule Framework will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [Unreleased] 9 | 10 | ### Added 11 | - 12 | 13 | ### Changed 14 | - 15 | 16 | ### Fixed 17 | - 18 | 19 | ## [1.2.1] - 2025-07-21 20 | 21 | ## [1.2.1](https://github.com/fbrbovic/cursor-rule-framework/compare/v1.2.0...v1.2.1) (2025-07-21) 22 | 23 | ## [Unreleased] 24 | 25 | ### Added 26 | - 27 | 28 | ### Changed 29 | - 30 | 31 | ### Fixed 32 | - 33 | 34 | ## [1.2.0] - 2025-06-08 35 | 36 | # [1.2.0](https://github.com/fbrbovic/cursor-rule-framework/compare/v1.1.0...v1.2.0) (2025-06-08) 37 | 38 | ## [Unreleased] 39 | 40 | ### Added 41 | - 42 | 43 | ### Changed 44 | - 45 | 46 | ### Fixed 47 | - 48 | 49 | ## [1.1.0] - 2025-06-08 50 | 51 | # [1.1.0](https://github.com/fbrbovic/cursor-rule-framework/compare/v1.0.1...v1.1.0) (2025-06-08) 52 | 53 | ## [Unreleased] 54 | 55 | ### Added 56 | - 57 | 58 | ### Changed 59 | - 60 | 61 | ### Fixed 62 | - 63 | 64 | ## [1.0.1] - 2025-06-07 65 | 66 | ## Initial Release 67 | 68 | This is the first release of the Cursor Rule Framework, a comprehensive system for AI-assisted development with Cursor IDE. 69 | 70 | ### 🎯 Key Features 71 | - Complete cursor rule management system 72 | - AI-driven development workflow (Blueprint → Construct → Validate) 73 | - Epic planning and tracking system 74 | - Architecture guidelines and validation 75 | - Comprehensive documentation and examples 76 | 77 | ### 📚 Documentation 78 | - Getting started guide 79 | - Rule organization best practices 80 | - Workflow system documentation 81 | - Epic planning guide 82 | - Custom rules creation 83 | - Team integration patterns 84 | 85 | ### 🛠️ Examples 86 | - Frontend development templates 87 | - Backend API patterns 88 | - Full-stack application setup 89 | - Monorepo configuration 90 | 91 | See the [complete documentation](docs/README.md) for detailed usage instructions. 92 | 93 | ## [Unreleased] 94 | 95 | ### Added 96 | - Initial framework documentation 97 | - Example projects for different technology stacks 98 | 99 | ### Changed 100 | - N/A 101 | 102 | ### Deprecated 103 | - N/A 104 | 105 | ### Removed 106 | - N/A 107 | 108 | ### Fixed 109 | - N/A 110 | 111 | ### Security 112 | - N/A 113 | 114 | ## [1.0.0] - 2025-01-16 115 | 116 | ### Added 117 | - **Core Rule Framework**: Complete cursor rule management system 118 | - `cursor-rules-management.mdc` - Comprehensive rule organization and metadata preservation 119 | - `project-config.mdc` - Project-specific configuration template 120 | - `workflow-state.mdc` - AI-driven development workflow with epic integration 121 | - `epics.mdc` - Large initiative planning and tracking system 122 | - `architecture.mdc` - Architecture guidelines template 123 | 124 | - **Workflow System**: AI-driven development methodology with architecture integration 125 | - Blueprint phase with automatic epic context and architecture validation 126 | - Construct phase for AI-guided implementation with architecture updates and epic tracking 127 | - Validate phase with automatic epic progress updates and architecture verification 128 | 129 | - **Epic Management**: AI-driven project planning system 130 | - Natural language epic creation and management 131 | - Automatic epic-workflow integration through AI interpretation 132 | - Progress tracking with completion percentages and dates 133 | - Context-aware epic selection and step management 134 | 135 | - **Documentation Framework**: Comprehensive project documentation 136 | - Professional README with clear value proposition 137 | - Detailed contributing guidelines 138 | - Code of conduct with AI-specific considerations 139 | - Complete documentation structure 140 | 141 | - **Open Source Setup**: Production-ready open source project 142 | - MIT License for maximum compatibility 143 | - GitHub templates for issues and pull requests 144 | - Community guidelines and support channels 145 | - Contributor recognition system 146 | 147 | ### Technical Features 148 | - **MDC Metadata Validation**: Proper cursor rule format enforcement 149 | - **Location Policy**: Standardized `.cursor/rules/` directory structure 150 | - **Glob Pattern Support**: Context-aware rule application 151 | - **Rule Inheritance**: Global → Domain → Feature-specific rule hierarchy 152 | - **Architecture Integration**: Automatic architecture validation and documentation updates 153 | - **Epic-Workflow Integration**: Natural language epic management with automatic progress tracking 154 | - **Quality Gates**: Automated validation and testing requirements 155 | 156 | ### Documentation 157 | - **Rule Organization Guide**: How to structure and manage cursor rules 158 | - **Workflow System Guide**: Complete development phase documentation 159 | - **Epic Planning Guide**: Large-scale project management with AI 160 | - **Best Practices Guide**: Proven patterns for AI-assisted development 161 | - **Custom Rules Guide**: Creating domain-specific rules 162 | - **Team Integration Guide**: Multi-developer workflow patterns 163 | - **Architecture Patterns Guide**: Scalable system design principles 164 | - **Troubleshooting Guide**: Common issues and solutions 165 | 166 | ### Examples 167 | - **Frontend Setup**: React/Vue.js project templates 168 | - **Backend API**: Node.js/Python API development patterns 169 | - **Full-Stack Application**: Complete application template 170 | - **Monorepo**: Multi-package repository structure 171 | 172 | ## Version History Format 173 | 174 | ### Version Types 175 | - **Major (x.0.0)**: Breaking changes, new core features 176 | - **Minor (0.x.0)**: New features, backward compatible 177 | - **Patch (0.0.x)**: Bug fixes, documentation updates 178 | 179 | ### Change Categories 180 | - **Added**: New features, rules, or documentation 181 | - **Changed**: Modifications to existing functionality 182 | - **Deprecated**: Features marked for removal in future versions 183 | - **Removed**: Features removed in this version 184 | - **Fixed**: Bug fixes and corrections 185 | - **Security**: Security-related changes and fixes 186 | 187 | ## Contributing 188 | 189 | See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this changelog and the project. 190 | 191 | ## Links 192 | 193 | - [Repository](https://github.com/fbrbovic/cursor-rule-framework) 194 | - [Issues](https://github.com/fbrbovic/cursor-rule-framework/issues) 195 | - [Discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions) 196 | - [Releases](https://github.com/fbrbovic/cursor-rule-framework/releases) -------------------------------------------------------------------------------- /docs/smart-detection-examples.md: -------------------------------------------------------------------------------- 1 | # 🧠 Smart Detection Examples 2 | 3 | > **Real-world examples of how the enhanced release system handles various Cursor AI commit patterns** 4 | 5 | ## 🎯 Overview 6 | 7 | The enhanced release system now uses **smart detection** to trigger releases even when Cursor AI doesn't follow conventional commit formats perfectly. Here are real examples: 8 | 9 | ## ✅ **Successful Smart Detection Scenarios** 10 | 11 | ### **Scenario 1: Feature Addition Without `feat:` Prefix** 12 | ```bash 13 | # Cursor AI commits: 14 | git commit -m "Add new rule validation system" 15 | 16 | # Smart detection analysis: 17 | ✅ Commit keywords: "Add", "new" → suggests feature 18 | ✅ File changes: scripts/validate-rules.js (new file) 19 | 🎯 Result: Minor release (v1.2.0 → v1.3.0) 20 | 📝 Reason: "Smart detection: Commit message suggests new feature" 21 | ``` 22 | 23 | ### **Scenario 2: Documentation Updates** 24 | ```bash 25 | # Cursor AI commits: 26 | git commit -m "Update installation guide with new examples" 27 | 28 | # Smart detection analysis: 29 | ✅ File changes: docs/*.md files modified 30 | 🎯 Result: Patch release (v1.2.0 → v1.2.1) 31 | 📝 Reason: "Smart detection: Documentation updates" 32 | ``` 33 | 34 | ### **Scenario 3: New Cursor Rule Added** 35 | ```bash 36 | # Cursor AI commits: 37 | git commit -m "Create backend validation rule template" 38 | 39 | # Smart detection analysis: 40 | ✅ File changes: .cursor/rules/backend-validation.mdc (new file) 41 | ✅ Commit keywords: "Create" → suggests feature 42 | 🎯 Result: Minor release (v1.2.0 → v1.3.0) 43 | 📝 Reason: "Smart detection: New cursor rules added" 44 | ``` 45 | 46 | ### **Scenario 4: Bug Fix Without `fix:` Prefix** 47 | ```bash 48 | # Cursor AI commits: 49 | git commit -m "Resolve parsing issue in YAML frontmatter" 50 | 51 | # Smart detection analysis: 52 | ✅ Commit keywords: "Resolve", "issue" → suggests fix 53 | 🎯 Result: Patch release (v1.2.0 → v1.2.1) 54 | 📝 Reason: "Smart detection: Commit message suggests bug fix" 55 | ``` 56 | 57 | ### **Scenario 5: Workflow Improvements** 58 | ```bash 59 | # Cursor AI commits: 60 | git commit -m "Improve release automation workflow" 61 | 62 | # Smart detection analysis: 63 | ✅ File changes: .github/workflows/release.yml modified 64 | ✅ Commit keywords: "Improve" → suggests enhancement 65 | 🎯 Result: Patch release (v1.2.0 → v1.2.1) 66 | 📝 Reason: "Smart detection: Workflow improvements" 67 | ``` 68 | 69 | ## ⚠️ **Safety Scenarios** 70 | 71 | ### **Scenario 6: Potential Breaking Change Detected** 72 | ```bash 73 | # Cursor AI commits: 74 | git commit -m "Add breaking changes to rule format" 75 | 76 | # Smart detection analysis: 77 | ⚠️ Warning: Detected "breaking" keyword 78 | ✅ File changes: .cursor/rules/*.mdc modified 79 | 🎯 Result: Minor release (v1.2.0 → v1.3.0) + Warning 80 | 📝 Reason: "Smart detection: Commit message suggests new feature" 81 | 📢 Warning: "Auto-release will be PATCH/MINOR only. Use manual release for major versions." 82 | ``` 83 | 84 | ### **Scenario 7: Multiple File Types** 85 | ```bash 86 | # Cursor AI commits: 87 | git commit -m "Enhance validation with new script and docs" 88 | 89 | # Smart detection analysis: 90 | ✅ File changes: 91 | - scripts/validate-docs.js (new file) 92 | - docs/validation.md (modified) 93 | ✅ Commit keywords: "Enhance", "new" → suggests feature 94 | 🎯 Result: Minor release (v1.2.0 → v1.3.0) 95 | 📝 Reason: "Smart detection: Scripts/tools updated" 96 | ``` 97 | 98 | ## 🚫 **No Release Scenarios** 99 | 100 | ### **Scenario 8: Minor Code Style Changes** 101 | ```bash 102 | # Cursor AI commits: 103 | git commit -m "Adjust whitespace formatting" 104 | 105 | # Smart detection analysis: 106 | ❌ No significant file changes detected 107 | ❌ No release-worthy keywords found 108 | 🎯 Result: No release triggered 109 | 📝 Reason: "No significant changes detected" 110 | ``` 111 | 112 | ### **Scenario 9: Git Configuration Changes** 113 | ```bash 114 | # Cursor AI commits: 115 | git commit -m "Update .gitignore" 116 | 117 | # Smart detection analysis: 118 | ❌ Only configuration files changed 119 | ❌ No release-worthy patterns detected 120 | 🎯 Result: No release triggered 121 | 📝 Reason: "No significant changes detected" 122 | ``` 123 | 124 | ## 🔍 **Detection Priority Order** 125 | 126 | The system checks triggers in this order: 127 | 128 | 1. **Conventional Commits** (highest priority) 129 | - `feat:` → Minor release 130 | - `fix:`, `perf:` → Patch release 131 | 132 | 2. **File-Based Detection** 133 | - New cursor rules → Minor release 134 | - New scripts/tools → Minor release 135 | - Documentation changes → Patch release 136 | - Workflow changes → Patch release 137 | 138 | 3. **Keyword Analysis** (fallback) 139 | - Feature keywords: "add", "create", "new", "implement" → Minor 140 | - Fix keywords: "fix", "resolve", "correct", "repair" → Patch 141 | 142 | 4. **Safety Override** 143 | - Danger keywords: "breaking", "remove", "major" → Warning only 144 | 145 | ## 🎯 **Practical Workflow** 146 | 147 | ### **For Daily Development** 148 | ```bash 149 | # These all work automatically now: 150 | git commit -m "Add epic progress tracking" # ✅ Minor 151 | git commit -m "feat: add epic tracking" # ✅ Minor 152 | git commit -m "Fix validation bug" # ✅ Patch 153 | git commit -m "fix: resolve validation issue" # ✅ Patch 154 | git commit -m "Update README with examples" # ✅ Patch 155 | git commit -m "Create new rule template" # ✅ Minor 156 | git push origin main # ✅ Auto-release 157 | ``` 158 | 159 | ### **What Gets Detected** 160 | - ✅ **New features** (regardless of commit message format) 161 | - ✅ **Bug fixes** (with smart keyword detection) 162 | - ✅ **Documentation updates** (file-based detection) 163 | - ✅ **Tool improvements** (script/workflow changes) 164 | - ❌ **Breaking changes** (safety-blocked from auto-release) 165 | 166 | ## 📊 **Workflow Transparency** 167 | 168 | Every release shows exactly why it was triggered: 169 | 170 | ```bash 171 | 📋 Version: 1.2.0 → 1.3.0 (minor) 172 | 🎯 Release reason: Smart detection: Commit message suggests new feature 173 | 📁 Changed files: scripts/validate-rules.js, docs/validation.md 174 | ➕ Added files: scripts/validate-rules.js 175 | ``` 176 | 177 | ## 🔧 **Customization** 178 | 179 | You can adjust detection sensitivity by modifying patterns in `.github/workflows/release.yml`: 180 | 181 | ```bash 182 | # More aggressive feature detection: 183 | "(add|create|implement|introduce|new|feature|enhance|improve|build)" 184 | 185 | # More conservative (current): 186 | "(add|create|implement|introduce|new|feature|enhance|improve)" 187 | 188 | # Fix detection patterns: 189 | "(fix|resolve|correct|repair|patch|bug|issue)" 190 | ``` 191 | 192 | --- 193 | 194 | **🎉 Result**: Cursor AI can now trigger releases reliably regardless of commit message format, while maintaining all safety protections against accidental major releases! -------------------------------------------------------------------------------- /.cursor/rules/architecture.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: Contains comprehensive high, mid and low level information about our project software and cloud architecture. 3 | globs: 4 | alwaysApply: false 5 | --- 6 | **Instructions** 7 | This rule contains comprehensive overview of our Architecture. 8 | 9 | You are always to refer to this file when making any Architectual Decisions or building, tracking and making any plans. 10 | You are always to keep expanding this and any referred sub documents with any relevent information or plans about any levels of our architecture. 11 | 12 | Contains sections of various high level overviews of our architecture, each section might contain a reference to additional detailed doc, if it's there super important to always refer to it. 13 | 14 | # **Architecture Documentation** 15 | 16 | ## **AI & User Collaboration Protocol** 17 | 18 | ### **Update Guidelines** 19 | - **AI Updates**: AI should update this file during CONSTRUCT phase when implementing architectural changes 20 | - **User Updates**: Users can update this file directly when making architectural decisions 21 | - **Conflict Resolution**: Latest timestamp wins; conflicts should be noted in changelog 22 | - **Version Tracking**: All major changes should be logged with date and reason 23 | 24 | ### **Change Protocol** 25 | ``` 26 | ## Architecture Changelog 27 | - [YYYY-MM-DD] [AI/USER] [CHANGE_TYPE] - Brief description 28 | - [YYYY-MM-DD] [AI/USER] [CHANGE_TYPE] - Brief description 29 | ``` 30 | 31 | --- 32 | 33 | ## **High-Level Architecture** 34 | 35 | ### **System Overview** 36 | 37 | *No architecture defined yet. This will be populated as development progresses.* 38 | 39 | **Key Architectural Principles:** 40 | - [ ] Modular design with clear separation of concerns 41 | - [ ] Scalable and maintainable codebase 42 | - [ ] Security-first approach 43 | - [ ] Performance optimization 44 | - [ ] Code reusability and DRY principles 45 | 46 | ### **Technology Stack** 47 | 48 | *Technology stack will be documented here based on project-config.mdc and actual implementation choices.* 49 | 50 | ### **Deployment Architecture** 51 | 52 | *Deployment architecture will be defined here as infrastructure decisions are made.* 53 | 54 | --- 55 | 56 | ## **Domain Architecture** 57 | 58 | ### **Application Domains** 59 | 60 | *Application domains will be documented here as they are identified and implemented.* 61 | 62 | ### **Domain Boundaries** 63 | 64 | *Domain boundaries and interfaces will be defined here as the application grows.* 65 | 66 | --- 67 | 68 | ## **Technical Architecture** 69 | 70 | ### **Data Architecture** 71 | 72 | *Data architecture will be documented here including:* 73 | - Database schema design 74 | - Data flow patterns 75 | - Storage solutions 76 | - Data security and privacy 77 | 78 | ### **API Architecture** 79 | 80 | *API architecture will be documented here including:* 81 | - REST/GraphQL design patterns 82 | - Authentication and authorization 83 | - API versioning strategy 84 | - Error handling patterns 85 | 86 | ### **Frontend Architecture** 87 | 88 | *Frontend architecture will be documented here including:* 89 | - Component hierarchy and patterns 90 | - State management approach 91 | - Routing and navigation 92 | - UI/UX design system integration 93 | 94 | ### **Backend Architecture** 95 | 96 | *Backend architecture will be documented here including:* 97 | - Service layer organization 98 | - Business logic patterns 99 | - Integration patterns 100 | - Background job processing 101 | 102 | --- 103 | 104 | ## **Infrastructure Architecture** 105 | 106 | ### **Development Environment** 107 | 108 | *Development environment setup will be documented here.* 109 | 110 | ### **Production Environment** 111 | 112 | *Production environment will be documented here including:* 113 | - Hosting and deployment 114 | - Monitoring and logging 115 | - Backup and disaster recovery 116 | - Security and compliance 117 | 118 | --- 119 | 120 | ## **Security Architecture** 121 | 122 | ### **Authentication & Authorization** 123 | 124 | *Security architecture will be documented here including:* 125 | - Authentication mechanisms 126 | - Authorization patterns 127 | - Session management 128 | - Security headers and policies 129 | 130 | ### **Data Security** 131 | 132 | *Data security measures will be documented here.* 133 | 134 | --- 135 | 136 | ## **Architecture Decision Records (ADRs)** 137 | 138 | ### **Decision Template** 139 | ``` 140 | ### ADR-[NUMBER]: [TITLE] 141 | **Date**: [YYYY-MM-DD] 142 | **Status**: [Proposed/Accepted/Deprecated/Superseded] 143 | **Deciders**: [AI/User/Team] 144 | 145 | #### Context 146 | [What is the issue we're trying to solve?] 147 | 148 | #### Decision 149 | [What is the change we're making?] 150 | 151 | #### Consequences 152 | [What becomes easier or harder to do because of this change?] 153 | 154 | #### Alternatives Considered 155 | [What other options were evaluated?] 156 | ``` 157 | 158 | ### **Active Decisions** 159 | 160 | *No architectural decisions recorded yet. ADRs will be added as decisions are made.* 161 | 162 | --- 163 | 164 | ## **Architecture Validation Rules** 165 | 166 | ### **Validation Checklist** 167 | - [ ] **Consistency**: New components follow existing patterns 168 | - [ ] **Scalability**: Design supports expected growth 169 | - [ ] **Maintainability**: Code is readable and well-organized 170 | - [ ] **Security**: Security considerations are addressed 171 | - [ ] **Performance**: Performance impact is considered 172 | - [ ] **Testing**: Testability is built into the design 173 | 174 | ### **Integration Points** 175 | - **Epic Planning**: All epic steps should consider architectural impact 176 | - **Workflow Planning**: Blueprint phase must validate against this architecture 177 | - **Code Review**: Implementation should follow architectural decisions 178 | 179 | --- 180 | 181 | ## **Architecture Changelog** 182 | 183 | *Architecture changes will be logged here with timestamps and descriptions.* 184 | 185 | **Format**: [YYYY-MM-DD] [AI/USER] [ADD/MODIFY/REMOVE] - Description 186 | 187 | --- 188 | 189 | ## **Architecture References** 190 | 191 | *References to detailed architecture documents will be added here as they are created.* 192 | -------------------------------------------------------------------------------- /.cursor/rules/workflow-state.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: Used for when referering to workflow-state or when doing work on any epic 3 | globs: 4 | alwaysApply: false 5 | --- 6 | # workflow_state.md 7 | _Last updated: 2025-06-06_ 8 | 9 | ## State 10 | Phase: null 11 | Status: null 12 | CurrentItem: null 13 | EpicReference: null 14 | EpicPhase: null 15 | EpicStep: null 16 | 17 | ## Plan 18 | 19 | 20 | ## Rules 21 | > **Keep every major section under an explicit H2 (`##`) heading so the agent can locate them unambiguously.** 22 | 23 | ### [PHASE: ANALYZE] 24 | 1. Read **project_config.md**, relevant code & docs. 25 | 2. **Epic Integration Logic**: 26 | - If user request mentions epic work (e.g., "work on login from user management epic"), search epics.mdc 27 | - Identify matching epic, phase, and step from user's natural language description 28 | - Set CurrentItem to descriptive format, and set epic fields: 29 | - Set `EpicReference = EPIC_NAME` (if found) 30 | - Set `EpicPhase = PHASE_NAME` (if found) 31 | - Set `EpicStep = STEP_NAME` (if found) 32 | - If no epic context found, leave epic fields as null 33 | 3. Summarize requirements. *No code or planning.* 34 | 35 | ### [PHASE: BLUEPRINT] 36 | 1. **Architecture Validation**: Read architecture.mdc to understand current architecture and validate planned changes align with existing patterns and decisions. 37 | 2. If `EpicReference` exists, read epic context from epics.mdc for step requirements and acceptance criteria. 38 | 3. **Architecture Impact Assessment**: Evaluate if planned work requires architectural changes or updates. 39 | 4. Decompose task into ordered steps. 40 | 5. Write pseudocode or file-level diff outline under **## Plan**. 41 | 6. **Plan Architecture Updates**: Include steps to update architecture.mdc if architectural changes are being made. 42 | 7. Set `Status = NEEDS_PLAN_APPROVAL` and await user confirmation. 43 | 44 | ### [PHASE: CONSTRUCT] 45 | 1. Follow the approved **## Plan** exactly. 46 | 2. After each atomic change: 47 | - run test / linter commands specified in `project_config.md` 48 | - capture tool output in **## Log** 49 | 3. **Architecture Updates**: When implementing architectural changes, update architecture.mdc with new patterns, decisions, or modifications. 50 | 4. On success of all steps, set `Phase = VALIDATE`. 51 | 52 | ### [PHASE: VALIDATE] 53 | 1. Rerun full test suite & any E2E checks. 54 | 2. If clean, set `Status = COMPLETED`. 55 | 3. Trigger **RULE_ITERATE_01** when applicable. 56 | 57 | --- 58 | 59 | ### RULE_INIT_01 60 | Trigger ▶ `Phase == INIT` 61 | Action ▶ Ask user for first high-level task → `Phase = ANALYZE, Status = RUNNING`. 62 | 63 | ### RULE_ITERATE_01 64 | Trigger ▶ `Status == COMPLETED && Items contains unprocessed rows` 65 | Action ▶ 66 | 1. Set `CurrentItem` to next unprocessed row in **## Items**. 67 | 2. Parse epic reference if CurrentItem format is `EPIC_NAME > PHASE_NAME > STEP_NAME`. 68 | 3. Clear **## Log**, reset `Phase = ANALYZE, Status = READY`. 69 | 70 | ### RULE_LOG_ROTATE_01 71 | Trigger ▶ `length(## Log) > 5 000 chars` 72 | Action ▶ Summarise the top 5 findings from **## Log** into **## ArchiveLog**, then clear **## Log**. 73 | 74 | ### RULE_EPIC_UPDATE_01 75 | Trigger ▶ `Phase == VALIDATE && Status == COMPLETED && EpicReference != null` 76 | Action ▶ 77 | 1. Parse EpicReference, EpicPhase, and EpicStep to identify epic location in epics.mdc. 78 | 2. Update corresponding epic step status to include completion percentage, date, and notes. 79 | 3. Check if all steps in the phase are completed, update phase status accordingly. 80 | 4. Add completion entry to epic notes section with timestamp. 81 | 82 | ### RULE_EPIC_COMPLETION_ARCHIVE_01 83 | Trigger ▶ `Epic Status == COMPLETED in epics.mdc` 84 | Action ▶ 85 | 1. Identify completed epic(s) in the ACTIVE EPICS section of epics.mdc. 86 | 2. Move the completed epic from ACTIVE EPICS section to EPIC COMPLETION HISTORY section. 87 | 3. Update portfolio summary counts: decrease Active Epics, increase Completed Epics. 88 | 4. Preserve all epic details, phases, steps, and outcomes in the completion history. 89 | 5. Update Epic Status Summary section with current counts. 90 | 6. Log the epic archival in workflow ## Log section. 91 | 92 | ### RULE_ARCHITECTURE_UPDATE_01 93 | Trigger ▶ `Phase == CONSTRUCT && architectural changes are being implemented` 94 | Action ▶ 95 | 1. Identify the architectural change being made (new pattern, technology choice, design decision). 96 | 2. Update the relevant section in architecture.mdc with the new information. 97 | 3. Add entry to Architecture Changelog with timestamp and change type. 98 | 4. Log the architecture update in workflow ## Log section. 99 | 100 | ### RULE_ARCHITECTURE_VALIDATE_01 101 | Trigger ▶ `Phase == BLUEPRINT && CurrentItem involves architectural decisions` 102 | Action ▶ 103 | 1. Read current architecture.mdc to understand existing patterns and constraints. 104 | 2. Validate that planned changes align with existing architectural decisions. 105 | 3. Identify any conflicts with current architecture and note in plan. 106 | 4. Include architecture update steps in the plan if new patterns are being introduced. 107 | 108 | ### RULE_SUMMARY_01 109 | Trigger ▶ `Phase == VALIDATE && Status == COMPLETED` 110 | Action ▶ 111 | 1. Read `project_config.md`. 112 | 2. Construct the new changelog line: `- `. 113 | 3. Find the `## Changelog` heading in `project_config.md`. 114 | 4. Insert the new changelog line immediately after the `## Changelog` heading and its following newline (making it the new first item in the list). 115 | 116 | --- 117 | 118 | ## Epic Integration Usage 119 | 120 | ### **Realistic User Interactions** 121 | 122 | #### **Starting Epic Work** 123 | ```bash 124 | # User says: 125 | "Start working on the login component from the user management epic" 126 | 127 | # AI automatically: 128 | 1. Searches epics.mdc for user management epic 129 | 2. Finds the login component step in authentication phase 130 | 3. Sets CurrentItem: "Login component implementation" 131 | 4. Sets epic fields: 132 | EpicReference: USER_MGMT_EPIC 133 | EpicPhase: AUTHENTICATION_PHASE 134 | EpicStep: LOGIN_COMPONENT_STEP 135 | 5. Reads epic context during blueprint phase 136 | ``` 137 | 138 | #### **Epic Progress Updates** 139 | ```bash 140 | # User says: 141 | "Update the login component progress to 75%, core functionality is done but still need remember me feature" 142 | 143 | # AI automatically: 144 | 1. Finds current epic work in epics.mdc 145 | 2. Updates step status to IN_PROGRESS (75%) 146 | 3. Updates notes with user's progress description 147 | 4. Sets last updated date 148 | ``` 149 | 150 | #### **Standalone Work (No Epic)** 151 | ```bash 152 | # User says: 153 | "Fix the payment processing bug in checkout" 154 | 155 | # AI automatically: 156 | 1. No epic context mentioned, processes as standalone work 157 | 2. Sets CurrentItem: "Fix payment processing bug" 158 | 3. Leaves epic fields null: 159 | EpicReference: null 160 | EpicPhase: null 161 | EpicStep: null 162 | ``` 163 | 164 | ### **AI Epic Management Commands** 165 | The AI handles these natural language requests: 166 | - **"Plan an epic for [feature]"** → Creates new epic in epics.mdc 167 | - **"Work on [step] from [epic]"** → Starts workflow with epic context 168 | - **"Update progress on [current work]"** → Updates epic step status 169 | - **"Mark [step] as complete"** → Sets step to 100% and updates epic 170 | - **"Show epic status"** → Displays current epic progress 171 | 172 | --- 173 | 174 | ## Items 175 | | id | description | status | 176 | |----|-------------|--------| 177 | 178 | ## Log 179 | 180 | 181 | ## ArchiveLog 182 | 183 | -------------------------------------------------------------------------------- /scripts/validate-rules.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | const fs = require('fs'); 4 | const path = require('path'); 5 | const yaml = require('js-yaml'); 6 | 7 | /** 8 | * Validates cursor rule files for proper MDC format and structure 9 | */ 10 | class RuleValidator { 11 | constructor() { 12 | this.errors = []; 13 | this.warnings = []; 14 | this.validatedFiles = 0; 15 | } 16 | 17 | /** 18 | * Validate a single rule file 19 | */ 20 | validateRule(filePath) { 21 | try { 22 | const content = fs.readFileSync(filePath, 'utf8'); 23 | const fileName = path.basename(filePath); 24 | 25 | console.log(`🔍 Validating ${fileName}...`); 26 | 27 | // Check file extension 28 | if (!filePath.endsWith('.mdc')) { 29 | this.addError(fileName, 'File must have .mdc extension'); 30 | return false; 31 | } 32 | 33 | // Split content into parts 34 | const parts = content.split('---'); 35 | 36 | if (parts.length < 3) { 37 | this.addError(fileName, 'Missing YAML frontmatter (must start and end with ---)'); 38 | return false; 39 | } 40 | 41 | // Validate YAML frontmatter 42 | const yamlContent = parts[1].trim(); 43 | let metadata; 44 | 45 | try { 46 | metadata = yaml.load(yamlContent); 47 | } catch (yamlError) { 48 | this.addError(fileName, `Invalid YAML: ${yamlError.message}`); 49 | return false; 50 | } 51 | 52 | // Validate required fields 53 | this.validateMetadata(fileName, metadata); 54 | 55 | // Validate markdown content 56 | const markdownContent = parts.slice(2).join('---').trim(); 57 | this.validateMarkdown(fileName, markdownContent); 58 | 59 | this.validatedFiles++; 60 | console.log(`✅ ${fileName} is valid`); 61 | return true; 62 | 63 | } catch (error) { 64 | this.addError(path.basename(filePath), `Failed to read file: ${error.message}`); 65 | return false; 66 | } 67 | } 68 | 69 | /** 70 | * Validate YAML metadata 71 | */ 72 | validateMetadata(fileName, metadata) { 73 | const required = ['description', 'globs', 'alwaysApply']; 74 | 75 | for (const field of required) { 76 | if (!(field in metadata)) { 77 | this.addError(fileName, `Missing required field: ${field}`); 78 | } 79 | } 80 | 81 | // Validate field types 82 | if (metadata.description && typeof metadata.description !== 'string') { 83 | this.addError(fileName, 'description must be a string'); 84 | } 85 | 86 | if (metadata.globs && typeof metadata.globs !== 'string') { 87 | this.addError(fileName, 'globs must be a string'); 88 | } 89 | 90 | if (metadata.alwaysApply && typeof metadata.alwaysApply !== 'boolean') { 91 | this.addError(fileName, 'alwaysApply must be a boolean (true/false)'); 92 | } 93 | 94 | // Validate description length 95 | if (metadata.description && metadata.description.length > 200) { 96 | this.addWarning(fileName, 'description is quite long (>200 chars), consider shortening'); 97 | } 98 | 99 | // Validate glob patterns 100 | if (metadata.globs) { 101 | this.validateGlobPatterns(fileName, metadata.globs); 102 | } 103 | } 104 | 105 | /** 106 | * Validate glob patterns 107 | */ 108 | validateGlobPatterns(fileName, globs) { 109 | // Basic glob pattern validation 110 | const suspiciousPatterns = [ 111 | /\*\*\*+/, // Too many asterisks 112 | /\/\//, // Double slashes 113 | /\s/, // Whitespace in glob 114 | ]; 115 | 116 | for (const pattern of suspiciousPatterns) { 117 | if (pattern.test(globs)) { 118 | this.addWarning(fileName, `Potentially problematic glob pattern: ${globs}`); 119 | break; 120 | } 121 | } 122 | } 123 | 124 | /** 125 | * Validate markdown content 126 | */ 127 | validateMarkdown(fileName, content) { 128 | if (!content || content.length === 0) { 129 | this.addError(fileName, 'Rule content cannot be empty'); 130 | return; 131 | } 132 | 133 | // Check for proper heading structure 134 | if (!content.includes('#')) { 135 | this.addWarning(fileName, 'Rule should include markdown headings for better structure'); 136 | } 137 | 138 | // Check for very short content 139 | if (content.length < 100) { 140 | this.addWarning(fileName, 'Rule content is quite short, consider adding more detail'); 141 | } 142 | 143 | // Check for common markdown issues 144 | const lines = content.split('\n'); 145 | let inCodeBlock = false; 146 | 147 | for (let i = 0; i < lines.length; i++) { 148 | const line = lines[i]; 149 | const lineNum = i + 1; 150 | 151 | // Track code blocks 152 | if (line.trim().startsWith('```')) { 153 | inCodeBlock = !inCodeBlock; 154 | } 155 | 156 | // Check for unbalanced markdown 157 | if (!inCodeBlock) { 158 | const backticks = (line.match(/`/g) || []).length; 159 | if (backticks % 2 !== 0) { 160 | this.addWarning(fileName, `Line ${lineNum}: Unbalanced backticks`); 161 | } 162 | } 163 | } 164 | 165 | if (inCodeBlock) { 166 | this.addError(fileName, 'Unclosed code block (missing closing ```)'); 167 | } 168 | } 169 | 170 | /** 171 | * Add an error 172 | */ 173 | addError(fileName, message) { 174 | this.errors.push({ file: fileName, message, type: 'error' }); 175 | console.log(`❌ ${fileName}: ${message}`); 176 | } 177 | 178 | /** 179 | * Add a warning 180 | */ 181 | addWarning(fileName, message) { 182 | this.warnings.push({ file: fileName, message, type: 'warning' }); 183 | console.log(`⚠️ ${fileName}: ${message}`); 184 | } 185 | 186 | /** 187 | * Validate all rule files in a directory 188 | */ 189 | validateDirectory(dirPath) { 190 | if (!fs.existsSync(dirPath)) { 191 | console.log(`❌ Directory ${dirPath} does not exist`); 192 | return false; 193 | } 194 | 195 | const files = fs.readdirSync(dirPath) 196 | .filter(file => file.endsWith('.mdc')) 197 | .map(file => path.join(dirPath, file)); 198 | 199 | if (files.length === 0) { 200 | console.log(`⚠️ No .mdc files found in ${dirPath}`); 201 | return true; 202 | } 203 | 204 | console.log(`🔍 Found ${files.length} rule files to validate\n`); 205 | 206 | let allValid = true; 207 | for (const file of files) { 208 | const isValid = this.validateRule(file); 209 | if (!isValid) { 210 | allValid = false; 211 | } 212 | } 213 | 214 | return allValid; 215 | } 216 | 217 | /** 218 | * Print validation summary 219 | */ 220 | printSummary() { 221 | console.log('\n📊 Validation Summary'); 222 | console.log('===================='); 223 | console.log(`Files validated: ${this.validatedFiles}`); 224 | console.log(`Errors: ${this.errors.length}`); 225 | console.log(`Warnings: ${this.warnings.length}`); 226 | 227 | if (this.errors.length === 0 && this.warnings.length === 0) { 228 | console.log('🎉 All rules are valid!'); 229 | return true; 230 | } 231 | 232 | if (this.errors.length > 0) { 233 | console.log('\n❌ Errors (must be fixed):'); 234 | this.errors.forEach(err => { 235 | console.log(` • ${err.file}: ${err.message}`); 236 | }); 237 | } 238 | 239 | if (this.warnings.length > 0) { 240 | console.log('\n⚠️ Warnings (recommended fixes):'); 241 | this.warnings.forEach(warn => { 242 | console.log(` • ${warn.file}: ${warn.message}`); 243 | }); 244 | } 245 | 246 | return this.errors.length === 0; 247 | } 248 | } 249 | 250 | /** 251 | * Main execution 252 | */ 253 | function main() { 254 | console.log('🎯 Cursor Rule Framework - Rule Validator'); 255 | console.log('==========================================\n'); 256 | 257 | const validator = new RuleValidator(); 258 | 259 | // Validate .cursor/rules directory 260 | const rulesDir = path.join(process.cwd(), '.cursor', 'rules'); 261 | const success = validator.validateDirectory(rulesDir); 262 | 263 | // Print summary 264 | const allValid = validator.printSummary(); 265 | 266 | // Exit with appropriate code 267 | process.exit(allValid ? 0 : 1); 268 | } 269 | 270 | // Run if called directly 271 | if (require.main === module) { 272 | main(); 273 | } 274 | 275 | module.exports = { RuleValidator }; -------------------------------------------------------------------------------- /docs/release-management.md: -------------------------------------------------------------------------------- 1 | # 🚀 Release Management Guide 2 | 3 | This guide covers the complete release management system for the Cursor Rule Framework, including automated workflows, versioning strategy, and best practices. 4 | 5 | ## 📋 Overview 6 | 7 | Our release system follows open source best practices with: 8 | 9 | - **Semantic Versioning (SemVer)**: Clear version numbering strategy 10 | - **Automated Releases**: GitHub Actions workflows for consistent releases 11 | - **Changelog Generation**: Automatic release notes from commits 12 | - **Quality Gates**: Validation before releases 13 | - **Multiple Release Types**: Patch, minor, major, and prerelease support 14 | - **Release Assets**: Downloadable bundles for users 15 | 16 | ## 🏷️ Versioning Strategy 17 | 18 | We follow [Semantic Versioning](https://semver.org/) with the format `MAJOR.MINOR.PATCH`: 19 | 20 | ### Version Types 21 | 22 | | Type | Format | When to Use | Examples | 23 | |------|--------|-------------|----------| 24 | | **Major** | `X.0.0` | Breaking changes, new core architecture | `1.0.0` → `2.0.0` | 25 | | **Minor** | `0.X.0` | New features, backward compatible | `1.1.0` → `1.2.0` | 26 | | **Patch** | `0.0.X` | Bug fixes, documentation updates | `1.1.1` → `1.1.2` | 27 | | **Prerelease** | `0.0.0-alpha.X` | Testing, beta features | `1.2.0-beta.1` | 28 | 29 | ### Conventional Commits 30 | 31 | Our automated release system triggers based on conventional commit messages: 32 | 33 | ```bash 34 | # Triggers PATCH release 35 | fix: resolve issue with rule validation 36 | docs: update installation guide 37 | 38 | # Triggers MINOR release 39 | feat: add new architecture validation rules 40 | feat: implement epic progress tracking 41 | 42 | # Triggers MAJOR release 43 | feat!: restructure rule organization system 44 | BREAKING CHANGE: rule format has changed 45 | 46 | # Prerelease (manual only) 47 | feat: experimental AI suggestions feature 48 | ``` 49 | 50 | ## 🤖 Automated Release Workflow 51 | 52 | ### Trigger Conditions 53 | 54 | **Automatic Releases** (on push to `main`): 55 | - Commits with `feat:`, `fix:`, `perf:`, or `BREAKING CHANGE:` 56 | - Creates releases automatically based on commit type 57 | 58 | **Manual Releases** (workflow dispatch): 59 | - Triggered manually from GitHub Actions tab 60 | - Choose release type: patch, minor, major, prerelease 61 | - Specify prerelease identifier: alpha, beta, rc 62 | 63 | ### Workflow Steps 64 | 65 | 1. **🔍 Validation Phase** 66 | - Validate cursor rules (`.mdc` format, YAML frontmatter) 67 | - Validate documentation (broken links, formatting) 68 | - Run quality checks 69 | 70 | 2. **📝 Version Calculation** 71 | - Determine new version based on commit messages or manual input 72 | - Update `package.json` version 73 | - Generate changelog from commits 74 | 75 | 3. **🏷️ Tagging & Assets** 76 | - Create Git tag with new version 77 | - Generate release assets: 78 | - Complete framework bundle 79 | - Quick-start bundle (essential rules only) 80 | - SHA256 checksums 81 | 82 | 4. **🚀 GitHub Release** 83 | - Create GitHub release with generated changelog 84 | - Upload release assets 85 | - Update CHANGELOG.md 86 | 87 | 5. **📊 Post-Release** 88 | - Commit changelog updates 89 | - Generate release summary 90 | - Notify about release completion 91 | 92 | ## 📦 Release Assets 93 | 94 | Each release includes these downloadable assets: 95 | 96 | ### Complete Framework Bundle 97 | ```bash 98 | cursor-rule-framework-v{VERSION}.tar.gz 99 | ``` 100 | - All documentation and examples 101 | - Complete `.cursor/rules/` directory 102 | - README, LICENSE, CHANGELOG 103 | 104 | ### Quick-Start Bundle 105 | ```bash 106 | quick-start-v{VERSION}.tar.gz 107 | ``` 108 | - Essential `.cursor/rules/` only 109 | - README and LICENSE 110 | - Minimal setup for immediate use 111 | 112 | ### Checksums 113 | ```bash 114 | checksums.txt 115 | ``` 116 | - SHA256 hashes for all assets 117 | - Verify download integrity 118 | 119 | ## 🔧 Manual Release Process 120 | 121 | ### For Maintainers 122 | 123 | **Option 1: GitHub Actions UI** 124 | 1. Go to **Actions** tab → **Release** workflow 125 | 2. Click **Run workflow** 126 | 3. Select release type and prerelease identifier (if applicable) 127 | 4. Click **Run workflow** 128 | 129 | **Option 2: Command Line** 130 | ```bash 131 | # Patch release 132 | npm run release:patch 133 | 134 | # Minor release 135 | npm run release:minor 136 | 137 | # Major release 138 | npm run release:major 139 | 140 | # Prerelease 141 | npm run release:prerelease 142 | ``` 143 | 144 | **Option 3: Using Git Tags** 145 | ```bash 146 | # Create and push tag 147 | git tag v1.2.3 148 | git push origin v1.2.3 149 | 150 | # The release workflow will trigger automatically 151 | ``` 152 | 153 | ### For Contributors 154 | 155 | Contributors cannot directly create releases, but can: 156 | 157 | 1. **Use Conventional Commits** for automatic releases: 158 | ```bash 159 | git commit -m "feat: add new rule validation system" 160 | ``` 161 | 162 | 2. **Request a Release** by creating an issue: 163 | ```markdown 164 | **Release Request** 165 | 166 | - Type: Minor 167 | - Reason: New features ready for release 168 | - Changes: List key changes since last release 169 | ``` 170 | 171 | ## 📋 Pre-Release Checklist 172 | 173 | Before any release, ensure: 174 | 175 | ### Code Quality 176 | - [ ] All tests pass 177 | - [ ] No linting errors 178 | - [ ] Rule validation passes (`npm run validate:rules`) 179 | - [ ] Documentation validation passes (`npm run validate:docs`) 180 | 181 | ### Documentation 182 | - [ ] CHANGELOG.md is up to date 183 | - [ ] README.md reflects current features 184 | - [ ] All links work correctly 185 | - [ ] Examples are current and functional 186 | 187 | ### Testing 188 | - [ ] Manual testing of key features 189 | - [ ] Example projects work correctly 190 | - [ ] New rules validate properly 191 | - [ ] Installation instructions are accurate 192 | 193 | ### Release Notes 194 | - [ ] Changelog includes all significant changes 195 | - [ ] Breaking changes are clearly documented 196 | - [ ] Migration guides provided (if needed) 197 | - [ ] Known issues documented 198 | 199 | ## 🐛 Troubleshooting Releases 200 | 201 | ### Common Issues 202 | 203 | **Release workflow fails** 204 | ```bash 205 | # Check workflow logs in GitHub Actions 206 | # Common causes: 207 | # - Validation failures 208 | # - Permission issues 209 | # - Invalid version format 210 | ``` 211 | 212 | **Missing release assets** 213 | ```bash 214 | # Re-run the release workflow 215 | # Or upload assets manually: 216 | gh release upload v1.2.3 assets/*.tar.gz 217 | ``` 218 | 219 | **Changelog not updated** 220 | ```bash 221 | # Manually update and commit: 222 | npm run changelog 223 | git add CHANGELOG.md 224 | git commit -m "docs: update changelog for v1.2.3" 225 | git push origin main 226 | ``` 227 | 228 | ### Recovery Procedures 229 | 230 | **Fix a failed release**: 231 | 1. Delete the problematic tag and release 232 | 2. Fix the underlying issue 233 | 3. Re-run the release workflow 234 | 235 | **Emergency hotfix**: 236 | 1. Create hotfix branch from latest release tag 237 | 2. Apply minimal fix 238 | 3. Create patch release directly from hotfix branch 239 | 240 | ## 📈 Release Analytics 241 | 242 | ### GitHub Insights 243 | - **Releases**: Track download metrics 244 | - **Traffic**: Monitor documentation views 245 | - **Issues**: Correlate releases with bug reports 246 | 247 | ### Monitoring 248 | ```bash 249 | # Check release assets downloads 250 | gh api repos/fbrbovic/cursor-rule-framework/releases 251 | 252 | # Monitor release frequency 253 | git tag --list | grep -E '^v[0-9]' | sort -V 254 | 255 | # Track changelog growth 256 | wc -l CHANGELOG.md 257 | ``` 258 | 259 | ## 🎯 Best Practices 260 | 261 | ### For Maintainers 262 | 263 | 1. **Regular Releases**: 264 | - Aim for releases every 2-4 weeks 265 | - Don't let changes accumulate too long 266 | 267 | 2. **Quality First**: 268 | - Never skip validation steps 269 | - Test thoroughly before releasing 270 | 271 | 3. **Clear Communication**: 272 | - Write descriptive release notes 273 | - Highlight breaking changes prominently 274 | 275 | 4. **Version Planning**: 276 | - Plan major releases carefully 277 | - Communicate breaking changes in advance 278 | 279 | ### For Contributors 280 | 281 | 1. **Conventional Commits**: 282 | - Use clear, descriptive commit messages 283 | - Follow the conventional format for automatic releases 284 | 285 | 2. **Documentation**: 286 | - Update docs with your changes 287 | - Include examples where helpful 288 | 289 | 3. **Testing**: 290 | - Test your changes thoroughly 291 | - Include validation scripts if needed 292 | 293 | ## 🔮 Future Enhancements 294 | 295 | Planned improvements to the release system: 296 | 297 | - **Automated Testing**: Integration tests before releases 298 | - **Release Scheduling**: Automated periodic releases 299 | - **Notification System**: Slack/Discord notifications 300 | - **Metrics Dashboard**: Release analytics and insights 301 | - **Release Candidates**: Automatic RC creation before major releases 302 | 303 | ## 🔗 Related Documentation 304 | 305 | - **[Contributing Guide](../CONTRIBUTING.md)** - How to contribute to the project 306 | - **[Changelog](../CHANGELOG.md)** - Complete project history 307 | - **[GitHub Releases](https://github.com/fbrbovic/cursor-rule-framework/releases)** - All releases 308 | - **[Semantic Versioning](https://semver.org/)** - Versioning specification 309 | - **[Keep a Changelog](https://keepachangelog.com/)** - Changelog format 310 | 311 | --- 312 | 313 | **Questions about releases?** Create an [issue](https://github.com/fbrbovic/cursor-rule-framework/issues) or start a [discussion](https://github.com/fbrbovic/cursor-rule-framework/discussions)! -------------------------------------------------------------------------------- /docs/ai-safe-commits.md: -------------------------------------------------------------------------------- 1 | # 🤖 AI-Safe Commit Guidelines 2 | 3 | > **Preventing Accidental Major Releases with AI-Generated Commits** 4 | 5 | ## 🎯 Overview 6 | 7 | This guide ensures safe collaboration between human developers and AI assistants (like Cursor AI) to prevent accidental major version releases while maintaining automated release workflows. 8 | 9 | ## 🚨 Safety Mechanisms 10 | 11 | Our release system includes multiple AI-safety features: 12 | 13 | ### 🔒 **No Automatic Major Releases** 14 | - **Automatic triggers**: Only `patch` and `minor` releases 15 | - **Major releases**: Must be triggered manually via GitHub Actions UI 16 | - **Safety net**: Code will error if major release attempts automatic trigger 17 | 18 | ### 🔍 **Smart Pattern Detection** 19 | - **Conventional Commits**: Respects `feat:`, `fix:`, `perf:` when used 20 | - **Smart File Analysis**: Detects changes when commit messages aren't conventional 21 | - **Keyword Analysis**: Scans commit content for feature/fix keywords 22 | - **Danger Detection**: Warns about potential breaking change language 23 | - **Safe Fallback**: Always defaults to patch/minor releases 24 | 25 | ### ✅ **Manual Approval for Major Changes** 26 | - Major releases require manual workflow dispatch 27 | - GitHub environment protection for production releases 28 | - Extra validation steps and warnings 29 | 30 | ## 📝 AI-Safe Commit Patterns 31 | 32 | ### ✅ **Safe Patterns (Auto-Release)** 33 | 34 | ```bash 35 | # CONVENTIONAL COMMITS (preferred) 36 | feat: add new architecture validation rules # → Minor release 37 | fix: resolve cursor rule validation issue # → Patch release 38 | docs: update installation instructions # → Patch release 39 | 40 | # SMART DETECTION - Works even without conventional format! 41 | Add new validation system # → Minor (keywords: "add", "new") 42 | Fix parsing issue in rules # → Patch (keywords: "fix") 43 | Update documentation with examples # → Patch (file changes: *.md) 44 | Create new cursor rule template # → Minor (new files + keywords) 45 | Improve workflow automation # → Patch (workflow files) 46 | ``` 47 | 48 | ### 🤖 **Smart Detection Logic** 49 | 50 | When Cursor AI doesn't use conventional commits, the system analyzes: 51 | 52 | **File Changes:** 53 | - **New files added** → Minor release (suggests new features) 54 | - **Documentation updates** → Patch release 55 | - **New cursor rules** → Minor release 56 | - **Modified cursor rules** → Patch release 57 | - **Script/tool changes** → Minor release 58 | - **Workflow updates** → Patch release 59 | - **Dependencies updated** → Patch release 60 | 61 | **Commit Message Keywords:** 62 | - **Feature words**: "add", "create", "implement", "new", "enhance" → Minor 63 | - **Fix words**: "fix", "resolve", "correct", "repair", "bug" → Patch 64 | - **Danger words**: "breaking", "remove", "delete", "major" → ⚠️ Warning 65 | 66 | **Smart Examples:** 67 | ```bash 68 | "Add new validation feature" # → Minor (keyword: "add", "new") 69 | "Update documentation" # → Patch (files: *.md) 70 | "Create rule template" # → Minor (new file + keywords) 71 | "Fix issue with parsing" # → Patch (keyword: "fix") 72 | "Improve workflow scripts" # → Minor (script changes) 73 | ``` 74 | 75 | ### ⚠️ **Dangerous Patterns (Manual Only)** 76 | 77 | ```bash 78 | # These patterns should NEVER be automatically generated by AI: 79 | 80 | # MAJOR release triggers (BLOCKED in automatic releases) 81 | feat!: restructure rule organization system 82 | BREAKING CHANGE: rule format has changed 83 | feat: complete API redesign (breaking change) 84 | 85 | # Patterns that trigger warnings but safe fallback: 86 | feat: add breaking changes to validation # → Warns but creates minor release 87 | fix: resolve major compatibility issue # → Warns but creates patch release 88 | ``` 89 | 90 | ## 🛡️ Cursor AI Configuration 91 | 92 | ### **Recommended Cursor Settings** 93 | 94 | Configure Cursor AI to avoid dangerous patterns: 95 | 96 | ```json 97 | // .cursor/settings.json 98 | { 99 | "ai.commitMessage.avoidPatterns": [ 100 | "BREAKING CHANGE", 101 | "breaking change", 102 | "feat!:", 103 | "!:", 104 | "major version", 105 | "major release", 106 | "breaking changes" 107 | ], 108 | "ai.commitMessage.preferredPatterns": [ 109 | "feat:", 110 | "fix:", 111 | "docs:", 112 | "style:", 113 | "refactor:", 114 | "test:", 115 | "chore:" 116 | ] 117 | } 118 | ``` 119 | 120 | ### **Safe AI Prompts** 121 | 122 | When asking Cursor AI for commit messages: 123 | 124 | ✅ **Good prompts:** 125 | ``` 126 | "Generate a conventional commit message for this feature addition" 127 | "Create a commit message for this bug fix" 128 | "Write a commit message for documentation updates" 129 | ``` 130 | 131 | ❌ **Avoid these prompts:** 132 | ``` 133 | "Generate a commit for this breaking change" 134 | "Create a major version commit message" 135 | "Write a commit that indicates API changes" 136 | ``` 137 | 138 | ## 🔧 Manual Major Release Process 139 | 140 | When you actually need a major release: 141 | 142 | ### **Step 1: Prepare** 143 | ```bash 144 | # Ensure you're ready for breaking changes 145 | git checkout main 146 | git pull origin main 147 | 148 | # Validate everything works 149 | npm run validate:rules 150 | npm run validate:docs 151 | npm test 152 | ``` 153 | 154 | ### **Step 2: Manual Trigger** 155 | 1. Go to **GitHub Actions** → **Release** workflow 156 | 2. Click **"Run workflow"** 157 | 3. Select **"major"** from release type dropdown 158 | 4. Click **"Run workflow"** 159 | 160 | ### **Step 3: Verify** 161 | - Check release notes mention breaking changes 162 | - Verify migration guides are included 163 | - Test release assets work correctly 164 | 165 | ## 📊 Monitoring AI Safety 166 | 167 | ### **Workflow Logs to Watch** 168 | 169 | The workflow will show these safety messages: 170 | 171 | ```bash 172 | ✅ Safe automatic release: 173 | "📋 Version: 1.2.3 → 1.3.0 (minor)" 174 | 175 | ⚠️ AI generated dangerous patterns: 176 | "⚠️ WARNING: Detected potential breaking change keywords in commit message" 177 | "⚠️ Auto-release will be PATCH/MINOR only. Use manual release for major versions." 178 | 179 | 🚨 Safety system activated: 180 | "🚨 ERROR: Major release attempted via automatic trigger" 181 | "🚨 This is not allowed for AI safety reasons" 182 | ``` 183 | 184 | ### **GitHub Actions Safety Features** 185 | 186 | - **Environment Protection**: Major releases require approval 187 | - **Pattern Detection**: Warns about dangerous commit messages 188 | - **Fail-Safe**: Exits with error if major release detected in auto mode 189 | - **Verbose Logging**: Clear visibility into release decisions 190 | 191 | ## 🎯 Best Practices 192 | 193 | ### **For Daily Development** 194 | 195 | 1. **Use conventional commits** for automatic releases: 196 | ```bash 197 | feat: add new rule validation 198 | fix: resolve parsing issue 199 | docs: update getting started guide 200 | ``` 201 | 202 | 2. **Review AI-generated commits** before pushing: 203 | ```bash 204 | git log -1 --oneline # Check the commit message 205 | git push origin main # Only push if safe 206 | ``` 207 | 208 | 3. **Let automation handle patch/minor releases**: 209 | - Push commits with confidence 210 | - Automatic releases every 2-4 weeks 211 | - No manual intervention needed 212 | 213 | ### **For Breaking Changes** 214 | 215 | 1. **Plan major releases carefully**: 216 | - Create RFC/issue for breaking changes 217 | - Communicate with users in advance 218 | - Prepare migration guides 219 | 220 | 2. **Use manual release process**: 221 | - Never rely on automatic triggers 222 | - Always use GitHub Actions UI 223 | - Include detailed release notes 224 | 225 | 3. **Test thoroughly**: 226 | - Validate all breaking changes 227 | - Test migration paths 228 | - Verify backward compatibility claims 229 | 230 | ## 🔍 Troubleshooting 231 | 232 | ### **AI Generated Dangerous Commits** 233 | 234 | If Cursor AI accidentally generates problematic patterns: 235 | 236 | ```bash 237 | # Option 1: Amend the commit message 238 | git commit --amend -m "feat: add new validation system" 239 | 240 | # Option 2: Reset and recommit 241 | git reset HEAD~1 242 | git add . 243 | git commit -m "feat: add new validation system" 244 | 245 | # Then push safely 246 | git push origin main 247 | ``` 248 | 249 | ### **False Positive Warnings** 250 | 251 | If the system warns about safe commits: 252 | 253 | 1. **Check the commit message** for unintended keywords 254 | 2. **Continue with confidence** - it will create a safe release 255 | 3. **Adjust the pattern** if false positives are common 256 | 257 | ### **Blocked Major Release** 258 | 259 | If you get a major release error: 260 | 261 | 1. **This is working as intended** - safety system activated 262 | 2. **Use manual process** via GitHub Actions UI 263 | 3. **Review why** the commit triggered major detection 264 | 265 | ## 📈 Configuration Options 266 | 267 | ### **Adjusting Safety Levels** 268 | 269 | You can customize the safety patterns in `.github/workflows/release.yml`: 270 | 271 | ```bash 272 | # Current detection pattern: 273 | "(BREAKING|breaking|major|MAJOR|!:|breaking change)" 274 | 275 | # To make it more/less strict: 276 | # More strict: "(BREAKING|breaking|major|MAJOR|!:|breaking change|change|update)" 277 | # Less strict: "(BREAKING CHANGE|feat!)" 278 | ``` 279 | 280 | ### **Emergency Override** 281 | 282 | In emergencies, you can temporarily disable safety: 283 | 284 | 1. **Edit the workflow file** to allow automatic major releases 285 | 2. **Make the emergency release** 286 | 3. **Immediately restore safety** mechanisms 287 | 288 | ## 🔗 Related Documentation 289 | 290 | - **[Release Management Guide](release-management.md)** - Complete release system 291 | - **[Contributing Guide](../CONTRIBUTING.md)** - Development workflow 292 | - **[Conventional Commits](https://www.conventionalcommits.org/)** - Commit message format 293 | 294 | --- 295 | 296 | **🤖 Safe AI Collaboration:** This system lets you work confidently with Cursor AI while preventing accidental breaking changes to your users! -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # 🎯 Cursor Rule Framework Examples 2 | 3 | This directory contains real-world examples demonstrating how to use the Cursor Rule Framework across different project types, technology stacks, and team sizes. 4 | 5 | ## 📚 Available Examples 6 | 7 | ### 🖥️ **Frontend Projects** 8 | 9 | #### [React TypeScript App](./frontend-react-typescript/) 10 | A complete React application with TypeScript, showcasing: 11 | - Component development rules 12 | - State management patterns 13 | - Testing strategies 14 | - Build optimization 15 | - **Tech Stack**: React 18, TypeScript, Vite, Vitest, ESLint 16 | 17 | #### [Vue.js Composition API](./frontend-vue-composition/) 18 | Modern Vue.js application using Composition API: 19 | - Vue 3 component patterns 20 | - Composable development 21 | - Pinia state management 22 | - TypeScript integration 23 | - **Tech Stack**: Vue 3, TypeScript, Vite, Pinia, Vitest 24 | 25 | #### [Next.js Full-Stack](./frontend-nextjs-fullstack/) 26 | Next.js application with API routes and database: 27 | - App Router patterns 28 | - Server Components 29 | - API development 30 | - Database integration 31 | - **Tech Stack**: Next.js 14, TypeScript, Prisma, tRPC 32 | 33 | ### 🔧 **Backend Projects** 34 | 35 | #### [Node.js Express API](./backend-nodejs-express/) 36 | RESTful API with Express and TypeScript: 37 | - REST API design patterns 38 | - Middleware development 39 | - Authentication & authorization 40 | - Database integration 41 | - **Tech Stack**: Node.js, Express, TypeScript, PostgreSQL, Prisma 42 | 43 | #### [Python FastAPI](./backend-python-fastapi/) 44 | Modern Python API with FastAPI: 45 | - Async API development 46 | - Pydantic models 47 | - Database migrations 48 | - Background tasks 49 | - **Tech Stack**: Python, FastAPI, SQLAlchemy, PostgreSQL, Redis 50 | 51 | #### [Encore.ts Microservices](./backend-encore-microservices/) 52 | Microservices architecture with Encore.ts: 53 | - Service design patterns 54 | - Inter-service communication 55 | - Database per service 56 | - Event-driven architecture 57 | - **Tech Stack**: Encore.ts, TypeScript, PostgreSQL, Redis 58 | 59 | ### 🚀 **Full-Stack Applications** 60 | 61 | #### [E-Commerce Platform](./fullstack-ecommerce/) 62 | Complete e-commerce solution: 63 | - User authentication 64 | - Product catalog 65 | - Shopping cart 66 | - Payment processing 67 | - Admin dashboard 68 | - **Tech Stack**: Next.js, Node.js, PostgreSQL, Stripe, Redis 69 | 70 | #### [SaaS Starter Kit](./fullstack-saas-starter/) 71 | Production-ready SaaS application template: 72 | - Multi-tenant architecture 73 | - Subscription management 74 | - Role-based permissions 75 | - Analytics dashboard 76 | - **Tech Stack**: Next.js, tRPC, Prisma, Clerk, Stripe 77 | 78 | ### 📦 **Monorepo Examples** 79 | 80 | #### [Turborepo Full-Stack](./monorepo-turborepo-fullstack/) 81 | Turborepo-managed workspace: 82 | - Shared packages 83 | - Multiple applications 84 | - Unified build pipeline 85 | - Shared component library 86 | - **Tech Stack**: Turborepo, Next.js, Express, TypeScript 87 | 88 | #### [Nx Enterprise](./monorepo-nx-enterprise/) 89 | Enterprise-scale monorepo with Nx: 90 | - Domain-driven architecture 91 | - Shared libraries 92 | - Code generation 93 | - Advanced caching 94 | - **Tech Stack**: Nx, Angular, NestJS, TypeScript 95 | 96 | ### 📱 **Mobile Development** 97 | 98 | #### [React Native Expo](./mobile-react-native-expo/) 99 | Cross-platform mobile application: 100 | - Native development patterns 101 | - State management 102 | - Navigation patterns 103 | - Platform-specific code 104 | - **Tech Stack**: React Native, Expo, TypeScript, Zustand 105 | 106 | ### 🔄 **DevOps & Infrastructure** 107 | 108 | #### [Docker Compose Setup](./devops-docker-compose/) 109 | Containerized development environment: 110 | - Multi-service orchestration 111 | - Development vs. production configs 112 | - Health checks and monitoring 113 | - **Tech Stack**: Docker, Docker Compose, PostgreSQL, Redis 114 | 115 | #### [CI/CD Pipeline](./devops-github-actions/) 116 | Complete CI/CD setup with GitHub Actions: 117 | - Automated testing 118 | - Code quality checks 119 | - Deployment automation 120 | - Environment management 121 | - **Tech Stack**: GitHub Actions, Docker, AWS/Vercel 122 | 123 | ## 🎯 How to Use These Examples 124 | 125 | ### 1. **Choose Your Example** 126 | Select the example that most closely matches your project type or technology stack. 127 | 128 | ### 2. **Copy the Structure** 129 | ```bash 130 | # Clone the entire framework 131 | git clone https://github.com/fbrbovic/cursor-rule-framework.git 132 | 133 | # Navigate to your chosen example 134 | cd cursor-rule-framework/examples/frontend-react-typescript 135 | 136 | # Copy to your project 137 | cp -r .cursor/ /path/to/your/project/ 138 | ``` 139 | 140 | ### 3. **Customize Rules** 141 | - Update `project-config.mdc` with your project details 142 | - Modify technology-specific rules as needed 143 | - Add domain-specific rules for your business logic 144 | 145 | ### 4. **Test Integration** 146 | ```bash 147 | # Open your project in Cursor IDE 148 | cursor /path/to/your/project 149 | 150 | # Verify rules are loaded 151 | # CMD/Ctrl + Shift + P → "Cursor: Rules" 152 | ``` 153 | 154 | ## 📖 Example Structure 155 | 156 | Each example follows this consistent structure: 157 | 158 | ``` 159 | example-name/ 160 | ├── .cursor/ 161 | │ └── rules/ 162 | │ ├── cursor-rules-management.mdc 163 | │ ├── project-config.mdc 164 | │ ├── workflow-state.mdc 165 | │ ├── epics.mdc 166 | │ ├── architecture.mdc 167 | │ └── [technology-specific rules] 168 | ├── src/ # Example source code 169 | ├── docs/ # Example-specific documentation 170 | ├── README.md # Setup and usage instructions 171 | └── package.json # Dependencies and scripts 172 | ``` 173 | 174 | ## 🎯 What You'll Learn 175 | 176 | Each example demonstrates: 177 | 178 | 1. **Rule Organization**: How to structure cursor rules for different project types 179 | 2. **AI-Driven Workflow**: Blueprint → Construct → Validate methodology with epic and architecture integration 180 | 3. **Architecture Integration**: Automatic validation and documentation of architectural decisions 181 | 4. **Quality Gates**: Automated testing, linting, and validation 182 | 5. **Team Collaboration**: Shared standards and knowledge preservation 183 | 6. **Epic Management**: Long-term project planning with AI assistance and architectural alignment 184 | 185 | ## 🎓 Learning Path 186 | 187 | ### **Beginner Path** 188 | 1. Start with [React TypeScript App](./frontend-react-typescript/) 189 | 2. Learn basic rule structure and organization 190 | 3. Practice with workflow phases and architecture integration 191 | 4. Experiment with custom rules 192 | 193 | ### **Intermediate Path** 194 | 1. Explore [Full-Stack SaaS](./fullstack-saas-starter/) 195 | 2. Understand multi-domain rule organization 196 | 3. Learn epic planning for larger features with architecture considerations 197 | 4. Practice team collaboration patterns 198 | 199 | ### **Advanced Path** 200 | 1. Study [Monorepo Enterprise](./monorepo-nx-enterprise/) 201 | 2. Master complex rule hierarchies and architecture documentation 202 | 3. Design custom workflow patterns with architecture validation 203 | 4. Create reusable rule libraries 204 | 205 | ## 🛠️ Customization Guidelines 206 | 207 | ### **Project-Specific Customization** 208 | 1. **Update Project Configuration** 209 | ```yaml 210 | # In project-config.mdc 211 | Project Goal: Your specific objectives 212 | Tech Stack: Your chosen technologies 213 | Critical Patterns: Your team's conventions 214 | ``` 215 | 216 | 2. **Add Domain Rules** 217 | ```bash 218 | # Create rules for your specific domains 219 | .cursor/rules/your-domain-rules.mdc 220 | ``` 221 | 222 | 3. **Configure Workflow** 223 | ```yaml 224 | # Customize workflow phases for your process 225 | # Add project-specific quality gates 226 | # Define team-specific validation steps 227 | ``` 228 | 229 | ### **Technology Stack Adaptation** 230 | 231 | #### **Different Frontend Framework** 232 | - Copy closest matching example 233 | - Update glob patterns for your file types 234 | - Modify component/module naming conventions 235 | - Adapt build and testing patterns 236 | 237 | #### **Different Backend Technology** 238 | - Adapt API design patterns 239 | - Update database integration rules 240 | - Modify deployment procedures 241 | - Adjust testing strategies 242 | 243 | #### **Different Infrastructure** 244 | - Update deployment targets 245 | - Modify CI/CD patterns 246 | - Adapt monitoring and logging 247 | - Adjust security policies 248 | 249 | ## 🧪 Testing Your Setup 250 | 251 | ### **Verification Checklist** 252 | - [ ] Rules appear in Cursor IDE rule picker 253 | - [ ] Glob patterns match your file structure 254 | - [ ] Workflow phases work with your process 255 | - [ ] Team members can access and use rules 256 | - [ ] Custom rules integrate properly 257 | 258 | ### **Common Issues** 259 | - **Rules not appearing**: Check file location and metadata format 260 | - **Wrong files matched**: Verify glob patterns 261 | - **Workflow conflicts**: Review phase definitions 262 | - **Team access issues**: Ensure proper rule sharing 263 | 264 | ## 🤝 Contributing Examples 265 | 266 | We welcome new examples! To contribute: 267 | 268 | 1. **Create Example Structure** 269 | ```bash 270 | mkdir examples/your-example-name 271 | cd examples/your-example-name 272 | ``` 273 | 274 | 2. **Follow Template Structure** 275 | - Include complete `.cursor/rules/` setup 276 | - Provide working source code example 277 | - Write comprehensive README 278 | - Add setup and usage instructions 279 | 280 | 3. **Document Your Example** 281 | - Explain technology choices 282 | - Highlight unique patterns 283 | - Include troubleshooting tips 284 | - Provide learning objectives 285 | 286 | 4. **Submit Pull Request** 287 | - Follow [Contributing Guidelines](../CONTRIBUTING.md) 288 | - Include example in this README 289 | - Provide comprehensive description 290 | 291 | ## 📞 Example-Specific Help 292 | 293 | Each example includes: 294 | - **README.md**: Setup and usage instructions 295 | - **docs/**: Detailed implementation guides 296 | - **troubleshooting.md**: Common issues and solutions 297 | 298 | For general framework questions, see the main [Documentation](../docs/README.md). 299 | 300 | --- 301 | 302 | **Ready to start?** Choose an example that matches your project and follow the setup instructions in its README! 303 | 304 | *Examples are continuously updated with new patterns and technologies. Last updated: January 16, 2025* -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing to Cursor Rule Framework 2 | 3 | First off, thank you for considering contributing to the Cursor Rule Framework! 🎉 4 | 5 | This framework helps developers worldwide build better software with AI assistance, and your contributions make that possible. 6 | 7 | ## 📋 Table of Contents 8 | 9 | - [Code of Conduct](#-code-of-conduct) 10 | - [Getting Started](#-getting-started) 11 | - [How Can I Contribute?](#-how-can-i-contribute) 12 | - [Development Guidelines](#-development-guidelines) 13 | - [Rule Development Standards](#-rule-development-standards) 14 | - [Pull Request Process](#-pull-request-process) 15 | - [Community](#-community) 16 | 17 | ## 📜 Code of Conduct 18 | 19 | This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. 20 | 21 | ## 🚀 Getting Started 22 | 23 | ### Prerequisites 24 | 25 | - **Cursor IDE** - [Download here](https://cursor.com/) 26 | - **Git** - Version control 27 | - **Basic knowledge** of Cursor AI features and MDC file format 28 | 29 | ### Local Development Setup 30 | 31 | 1. **Fork the repository** 32 | ```bash 33 | # Click "Fork" on GitHub, then clone your fork 34 | git clone https://github.com/YOUR_USERNAME/cursor-rule-framework.git 35 | cd cursor-rule-framework 36 | ``` 37 | 38 | 2. **Set up upstream remote** 39 | ```bash 40 | git remote add upstream https://github.com/original-owner/cursor-rule-framework.git 41 | ``` 42 | 43 | 3. **Open in Cursor IDE** 44 | ```bash 45 | cursor . 46 | ``` 47 | 48 | 4. **Test the framework** 49 | - Try the example workflows 50 | - Verify rules load correctly in Cursor 51 | - Test with a sample project 52 | 53 | ## 🤝 How Can I Contribute? 54 | 55 | ### 🐛 **Bug Reports** 56 | 57 | Found a bug? Help us fix it! 58 | 59 | **Before submitting:** 60 | - Check existing [issues](https://github.com/fbrbovic/cursor-rule-framework/issues) 61 | - Test with the latest version 62 | - Gather relevant information 63 | 64 | **Bug Report Template:** 65 | ```markdown 66 | **Description:** Clear description of the bug 67 | **Steps to Reproduce:** 68 | 1. Step one 69 | 2. Step two 70 | 3. Bug occurs 71 | 72 | **Expected Behavior:** What should happen 73 | **Actual Behavior:** What actually happens 74 | **Environment:** 75 | - Cursor IDE Version: 76 | - OS: 77 | - Framework Version: 78 | **Additional Context:** Screenshots, logs, etc. 79 | ``` 80 | 81 | ### 💡 **Feature Requests** 82 | 83 | Have an idea? We'd love to hear it! 84 | 85 | **Feature Request Template:** 86 | ```markdown 87 | **Problem:** What problem does this solve? 88 | **Solution:** Describe your proposed solution 89 | **Alternatives:** Any alternative approaches considered? 90 | **Implementation:** Technical approach (if known) 91 | **Impact:** Who benefits and how? 92 | ``` 93 | 94 | ### 📝 **Documentation Improvements** 95 | 96 | Documentation is crucial for adoption: 97 | - Fix typos or unclear explanations 98 | - Add missing examples 99 | - Improve existing guides 100 | - Create new tutorials 101 | - Translate documentation 102 | 103 | ### 🔧 **Code Contributions** 104 | 105 | #### Rule Contributions 106 | - New cursor rules for specific domains 107 | - Improvements to existing rules 108 | - Better rule organization patterns 109 | - Enhanced metadata structures 110 | 111 | #### Framework Improvements 112 | - Workflow enhancements 113 | - Better validation tools 114 | - Performance optimizations 115 | - New example projects 116 | 117 | ## 🛠️ Development Guidelines 118 | 119 | ### Branch Naming Convention 120 | 121 | ```bash 122 | feature/description-of-feature # New features 123 | bugfix/description-of-fix # Bug fixes 124 | docs/description-of-change # Documentation 125 | refactor/description-of-change # Code refactoring 126 | ``` 127 | 128 | ### Commit Message Format 129 | 130 | We follow [Conventional Commits](https://www.conventionalcommits.org/): 131 | 132 | ``` 133 | type(scope): description 134 | 135 | [optional body] 136 | 137 | [optional footer] 138 | ``` 139 | 140 | **Types:** 141 | - `feat`: New feature 142 | - `fix`: Bug fix 143 | - `docs`: Documentation changes 144 | - `style`: Code style changes 145 | - `refactor`: Code refactoring 146 | - `test`: Test additions/changes 147 | - `chore`: Maintenance tasks 148 | 149 | **Examples:** 150 | ```bash 151 | feat(rules): add TypeScript validation rule 152 | fix(workflow): correct blueprint phase validation 153 | docs(readme): improve quick start guide 154 | ``` 155 | 156 | ## 📐 Rule Development Standards 157 | 158 | ### MDC File Requirements 159 | 160 | All cursor rules must follow these standards: 161 | 162 | #### 1. **Proper Metadata** 163 | ```yaml 164 | --- 165 | description: Clear, concise description of the rule's purpose 166 | globs: pattern/to/match/**/*.ext 167 | alwaysApply: true/false 168 | --- 169 | ``` 170 | 171 | #### 2. **Clear Structure** 172 | ```markdown 173 | # Rule Title 174 | 175 | Brief description of what this rule does. 176 | 177 | ## When This Applies 178 | - Specific conditions 179 | - File types or patterns 180 | - Development phases 181 | 182 | ## Guidelines 183 | 1. Numbered guidelines 184 | 2. Clear and actionable 185 | 3. Include examples 186 | 187 | ## Examples 188 | Concrete examples of correct usage. 189 | 190 | ## Common Mistakes 191 | What to avoid and why. 192 | ``` 193 | 194 | #### 3. **File Naming** 195 | - Use kebab-case: `my-rule-name.mdc` 196 | - Be descriptive but concise 197 | - Include domain if applicable: `frontend-styling.mdc` 198 | 199 | #### 4. **Scope Appropriateness** 200 | - **Global rules** (`alwaysApply: true`): Apply to entire project 201 | - **Domain rules** (`alwaysApply: false`): Apply to specific file patterns 202 | - **Feature rules**: Apply to specific features or components 203 | 204 | ### Rule Quality Checklist 205 | 206 | Before submitting a rule, ensure: 207 | 208 | - [ ] **Clear Purpose**: Rule has a specific, well-defined purpose 209 | - [ ] **Proper Metadata**: All required metadata fields present 210 | - [ ] **Correct Globs**: File patterns match intended scope 211 | - [ ] **Actionable Guidelines**: Instructions are clear and specific 212 | - [ ] **Examples Included**: Concrete examples of usage 213 | - [ ] **Tested**: Rule works correctly in Cursor IDE 214 | - [ ] **Documented**: Purpose and usage are explained 215 | 216 | ### Testing Your Rules 217 | 218 | 1. **Functional Testing** 219 | ```bash 220 | # Open test project in Cursor 221 | cursor examples/test-project/ 222 | 223 | # Verify rule appears in Cursor's rule picker 224 | # Test rule application on relevant files 225 | # Confirm expected behavior 226 | ``` 227 | 228 | 2. **Integration Testing** 229 | ```bash 230 | # Test with different project types 231 | # Verify no conflicts with existing rules 232 | # Check performance impact 233 | ``` 234 | 235 | ## 🔄 Pull Request Process 236 | 237 | ### Before Submitting 238 | 239 | 1. **Update your fork** 240 | ```bash 241 | git checkout main 242 | git pull upstream main 243 | git push origin main 244 | ``` 245 | 246 | 2. **Create feature branch** 247 | ```bash 248 | git checkout -b feature/my-awesome-rule 249 | ``` 250 | 251 | 3. **Make your changes** 252 | - Follow development guidelines 253 | - Add/update tests if applicable 254 | - Update documentation 255 | 256 | 4. **Test thoroughly** 257 | - Test in multiple scenarios 258 | - Verify no breaking changes 259 | - Check rule validation 260 | 261 | ### PR Requirements 262 | 263 | - [ ] **Clear Description**: What does this PR do and why? 264 | - [ ] **Testing**: All changes tested locally 265 | - [ ] **Documentation**: Updated relevant docs 266 | - [ ] **No Breaking Changes**: Or clearly documented 267 | - [ ] **Rule Validation**: New rules follow standards 268 | - [ ] **Examples**: Include usage examples if applicable 269 | 270 | ### PR Template 271 | 272 | ```markdown 273 | ## Summary 274 | Brief description of changes 275 | 276 | ## Type of Change 277 | - [ ] Bug fix 278 | - [ ] New feature 279 | - [ ] Documentation update 280 | - [ ] Rule improvement 281 | - [ ] Breaking change 282 | 283 | ## Testing 284 | - [ ] Tested locally 285 | - [ ] Added/updated tests 286 | - [ ] Verified in Cursor IDE 287 | 288 | ## Checklist 289 | - [ ] Code follows style guidelines 290 | - [ ] Self-review completed 291 | - [ ] Documentation updated 292 | - [ ] No breaking changes (or documented) 293 | ``` 294 | 295 | ### Review Process 296 | 297 | 1. **Automated Checks**: Must pass all CI checks 298 | 2. **Maintainer Review**: Core team reviews code and design 299 | 3. **Community Feedback**: Open for community input 300 | 4. **Testing**: Validated in various environments 301 | 5. **Merge**: Approved PRs are merged to main 302 | 303 | ## 📖 Documentation Standards 304 | 305 | ### Writing Guidelines 306 | 307 | - **Clear and Concise**: Easy to understand for all skill levels 308 | - **Action-Oriented**: Focus on what users should do 309 | - **Examples**: Include practical examples 310 | - **Structured**: Use consistent formatting and organization 311 | - **Tested**: Verify all instructions work 312 | 313 | ### Documentation Types 314 | 315 | 1. **API Documentation**: Technical specifications 316 | 2. **Tutorials**: Step-by-step guides 317 | 3. **Examples**: Real-world usage patterns 318 | 4. **Reference**: Quick lookup information 319 | 320 | ## 🌟 Recognition 321 | 322 | Contributors are recognized in several ways: 323 | 324 | - **Contributors List**: Added to README.md 325 | - **Release Notes**: Major contributions highlighted 326 | - **Hall of Fame**: Special recognition for significant impact 327 | - **Maintainer Invitation**: Outstanding contributors may be invited as maintainers 328 | 329 | ## 💬 Community 330 | 331 | ### Getting Help 332 | 333 | - **Discussions**: [GitHub Discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions) 334 | - **Issues**: [Bug reports and feature requests](https://github.com/fbrbovic/cursor-rule-framework/issues) 335 | - **Wiki**: [Community knowledge base](https://github.com/fbrbovic/cursor-rule-framework/wiki) 336 | 337 | ### Communication Guidelines 338 | 339 | - **Be Respectful**: Treat everyone with kindness and respect 340 | - **Be Constructive**: Provide helpful, actionable feedback 341 | - **Be Patient**: Remember that volunteers maintain this project 342 | - **Be Clear**: Communicate clearly and provide context 343 | 344 | ## 🎯 Next Steps 345 | 346 | Ready to contribute? Here's how to get started: 347 | 348 | 1. **Choose an Issue**: Look for "good first issue" labels 349 | 2. **Ask Questions**: Don't hesitate to ask for clarification 350 | 3. **Start Small**: Begin with documentation or small improvements 351 | 4. **Share Ideas**: Discuss your ideas before implementing large changes 352 | 353 | ## 📞 Need Help? 354 | 355 | - **General Questions**: [GitHub Discussions](https://github.com/fbrbovic/cursor-rule-framework/discussions) 356 | - **Bug Reports**: [GitHub Issues](https://github.com/fbrbovic/cursor-rule-framework/issues) 357 | - **Security Issues**: Email security@your-domain.com 358 | 359 | --- 360 | 361 | **Thank you for contributing to the Cursor Rule Framework! 🙏** 362 | 363 | *Together, we're making AI-assisted development better for everyone.* -------------------------------------------------------------------------------- /docs/architecture.md: -------------------------------------------------------------------------------- 1 | # 🏗️ Architecture Documentation Guide 2 | 3 | This guide explains how to use the `.cursor/rules/architecture.mdc` rule for managing project architecture information and architectural decision-making with AI assistance. 4 | 5 | ## 🎯 Overview 6 | 7 | The `architecture.mdc` rule serves as your project's architectural knowledge base. It's designed to be a living document where AI assistants can both reference and contribute architectural information, ensuring architectural decisions are consistent and well-documented. 8 | 9 | ## 📋 Rule Purpose 10 | 11 | The `architecture.mdc` rule: 12 | 13 | - **Centralizes Architecture Knowledge**: Single source of truth for all architectural information 14 | - **Guides AI Decision Making**: AI refers to this file for architectural context 15 | - **Evolves with Project**: AI continuously updates and expands architectural documentation 16 | - **Maintains Consistency**: Ensures all architectural decisions align with established patterns 17 | 18 | ## 🔧 How It Works 19 | 20 | ### **AI Behavior with Architecture Rule** 21 | 22 | When the `architecture.mdc` rule is active, AI assistants will: 23 | 24 | 1. **Reference Before Decisions**: Check existing architecture before making any architectural recommendations 25 | 2. **Document New Decisions**: Add new architectural information to the file 26 | 3. **Maintain Consistency**: Ensure all suggestions align with documented architecture 27 | 4. **Expand Documentation**: Continuously improve and detail the architectural documentation 28 | 29 | ### **Rule Configuration** 30 | 31 | ```yaml 32 | --- 33 | description: Contains comprehensive high, mid and low level information about our project software and cloud architecture. 34 | globs: "**/*.*" 35 | alwaysApply: true 36 | --- 37 | ``` 38 | 39 | - **Always Applied**: This rule is active for all files in your project 40 | - **Global Scope**: Affects all architectural decisions across your codebase 41 | - **Comprehensive Coverage**: Includes high, mid, and low-level architectural information 42 | 43 | ## 📐 Architecture Documentation Structure 44 | 45 | ### **Recommended Sections** 46 | 47 | When AI populates your `architecture.mdc`, it should include: 48 | 49 | #### **High-Level Architecture** 50 | ```markdown 51 | ## System Architecture Overview 52 | - **Architecture Style**: [Microservices/Monolith/Serverless/etc.] 53 | - **Primary Patterns**: [Domain-Driven Design/Clean Architecture/etc.] 54 | - **Technology Stack**: [Languages, frameworks, databases] 55 | - **Deployment Strategy**: [Cloud platform, containerization] 56 | 57 | ## System Components 58 | ### Frontend 59 | - Framework and libraries 60 | - State management approach 61 | - UI/UX patterns 62 | 63 | ### Backend 64 | - API design patterns 65 | - Data access patterns 66 | - Business logic organization 67 | 68 | ### Data Layer 69 | - Database selection and design 70 | - Caching strategy 71 | - Data flow patterns 72 | ``` 73 | 74 | #### **Mid-Level Architecture** 75 | ```markdown 76 | ## Service Boundaries 77 | - Service responsibilities 78 | - Communication patterns 79 | - Data ownership 80 | 81 | ## Integration Patterns 82 | - API contracts 83 | - Message queues 84 | - Event-driven patterns 85 | 86 | ## Security Architecture 87 | - Authentication/authorization 88 | - Data protection 89 | - Security boundaries 90 | ``` 91 | 92 | #### **Low-Level Architecture** 93 | ```markdown 94 | ## Code Organization 95 | - Project structure 96 | - Naming conventions 97 | - Module boundaries 98 | 99 | ## Technical Patterns 100 | - Error handling strategies 101 | - Logging and monitoring 102 | - Performance considerations 103 | 104 | ## Development Practices 105 | - Testing strategies 106 | - Code review process 107 | - Documentation standards 108 | ``` 109 | 110 | ## 🚀 Usage Examples 111 | 112 | ### **Starting a New Project** 113 | 114 | When beginning a new project, AI will help establish your architecture: 115 | 116 | ```bash 117 | # Example conversation with AI 118 | "Help me design the architecture for a task management SaaS application" 119 | 120 | # AI will: 121 | 1. Ask clarifying questions about requirements 122 | 2. Propose architectural approaches 123 | 3. Document the chosen architecture in architecture.mdc 124 | 4. Reference this documentation in future decisions 125 | ``` 126 | 127 | ### **Making Architectural Changes** 128 | 129 | When modifying existing architecture: 130 | 131 | ```bash 132 | # Example conversation 133 | "I want to add real-time notifications to our app" 134 | 135 | # AI will: 136 | 1. Review current architecture from architecture.mdc 137 | 2. Propose integration approaches that fit existing patterns 138 | 3. Update architecture documentation with new components 139 | 4. Ensure consistency with established patterns 140 | ``` 141 | 142 | ### **Architecture Reviews** 143 | 144 | For reviewing and validating architecture: 145 | 146 | ```bash 147 | # Example conversation 148 | "Review our current architecture for scalability concerns" 149 | 150 | # AI will: 151 | 1. Analyze documented architecture 152 | 2. Identify potential bottlenecks 153 | 3. Suggest improvements 154 | 4. Update documentation with recommendations 155 | ``` 156 | 157 | ## 📚 Best Practices 158 | 159 | ### **Keep It Current** 160 | - Regularly review and update architectural documentation 161 | - Ensure changes are reflected promptly 162 | - Remove outdated patterns and decisions 163 | 164 | ### **Reference External Documents** 165 | ```markdown 166 | ## External Architecture Documents 167 | - [System Design Document](docs/system-design.md) 168 | - [API Specification](docs/api-spec.md) 169 | - [Database Schema](docs/database-schema.md) 170 | - [Deployment Guide](docs/deployment.md) 171 | ``` 172 | 173 | ### **Include Decision Rationale** 174 | ```markdown 175 | ## Architectural Decisions 176 | ### Decision: Microservices Architecture 177 | **Rationale**: High team autonomy, independent deployments, technology diversity 178 | **Trade-offs**: Increased complexity, network latency, distributed system challenges 179 | **Alternatives Considered**: Monolith, Modular monolith 180 | **Date**: 2024-01-15 181 | ``` 182 | 183 | ### **Maintain Consistency** 184 | - Use consistent terminology throughout 185 | - Follow established naming conventions 186 | - Align with team coding standards 187 | 188 | ## 🛠️ AI Integration Patterns 189 | 190 | ### **Architecture-First Development** 191 | 192 | ```bash 193 | # When planning new features 194 | "Plan a user authentication system for our app" 195 | 196 | # AI process: 197 | 1. Reviews architecture.mdc for existing auth patterns 198 | 2. Ensures new system aligns with security architecture 199 | 3. Documents authentication architecture decisions 200 | 4. Provides implementation guidance consistent with patterns 201 | ``` 202 | 203 | ### **Workflow Integration** 204 | 205 | The architecture rule seamlessly integrates with the three-phase workflow: 206 | 207 | #### **Blueprint Phase Integration** 208 | ```bash 209 | # During Blueprint phase, AI automatically: 210 | 1. Reads architecture.mdc for existing patterns and constraints 211 | 2. Validates planned changes against current architecture 212 | 3. Identifies architectural impact of new features 213 | 4. Includes architecture updates in implementation plan 214 | ``` 215 | 216 | #### **Construct Phase Integration** 217 | ```bash 218 | # During Construct phase, AI automatically: 219 | 1. Implements code following architectural patterns 220 | 2. Updates architecture.mdc with new decisions and patterns 221 | 3. Logs architectural changes with timestamps 222 | 4. Maintains consistency with established conventions 223 | ``` 224 | 225 | #### **Validate Phase Integration** 226 | ```bash 227 | # During Validate phase, AI automatically: 228 | 1. Verifies implementation follows architectural guidelines 229 | 2. Checks architecture documentation is up to date 230 | 3. Validates consistency across architectural decisions 231 | ``` 232 | 233 | ### **Epic Integration** 234 | 235 | Architecture considerations are built into epic planning: 236 | 237 | #### **Epic-Level Architecture Planning** 238 | ```bash 239 | # When creating epics, AI considers: 240 | 1. Architectural impact of epic on system design 241 | 2. New patterns or technologies being introduced 242 | 3. Alignment with existing architectural decisions 243 | 4. Cross-epic architectural consistency 244 | ``` 245 | 246 | #### **Step-Level Architecture Tracking** 247 | ```bash 248 | # Each epic step includes: 249 | - Architecture impact assessment 250 | - New patterns being introduced 251 | - Dependencies on existing architecture 252 | - Required updates to architecture.mdc 253 | ``` 254 | 255 | ### **Pattern Enforcement** 256 | 257 | ```bash 258 | # When implementing features 259 | "Create a new API endpoint for user management" 260 | 261 | # AI process: 262 | 1. References API design patterns from architecture.mdc 263 | 2. Follows established error handling patterns 264 | 3. Applies documented security patterns 265 | 4. Maintains consistency with existing endpoints 266 | ``` 267 | 268 | ### **Architecture Evolution** 269 | 270 | ```bash 271 | # When scaling systems 272 | "Our user base is growing rapidly, help optimize our architecture" 273 | 274 | # AI process: 275 | 1. Analyzes current architecture from documentation 276 | 2. Identifies scaling bottlenecks 277 | 3. Proposes evolution strategies 278 | 4. Updates architecture.mdc with scaling patterns 279 | ``` 280 | 281 | ## 📈 Advanced Usage 282 | 283 | ### **Multi-Domain Architecture** 284 | 285 | For complex projects with multiple domains: 286 | 287 | ```markdown 288 | ## Domain Architecture 289 | ### User Domain 290 | - User management services 291 | - Authentication components 292 | - Profile management 293 | 294 | ### Order Domain 295 | - Order processing services 296 | - Payment integration 297 | - Inventory management 298 | 299 | ### Shared Infrastructure 300 | - Common utilities 301 | - Shared databases 302 | - Cross-cutting concerns 303 | ``` 304 | 305 | ### **Migration Planning** 306 | 307 | For architecture migrations: 308 | 309 | ```markdown 310 | ## Migration Strategy 311 | ### Current State 312 | - Legacy monolith architecture 313 | - Coupled components 314 | - Single database 315 | 316 | ### Target State 317 | - Microservices architecture 318 | - Domain-separated services 319 | - Distributed data 320 | 321 | ### Migration Steps 322 | 1. Identify service boundaries 323 | 2. Extract shared libraries 324 | 3. Split database by domain 325 | 4. Implement service communication 326 | ``` 327 | 328 | ## 🔍 Troubleshooting 329 | 330 | ### **AI Not Following Architecture** 331 | 332 | If AI suggestions don't align with your architecture: 333 | 334 | 1. **Check Rule Activation**: Ensure `architecture.mdc` has `alwaysApply: true` 335 | 2. **Review Documentation**: Verify architecture is clearly documented 336 | 3. **Add Specific Patterns**: Include more detailed patterns and examples 337 | 4. **Explicit Instructions**: Add specific guidelines for AI behavior 338 | 339 | ### **Outdated Architecture Information** 340 | 341 | If architecture documentation becomes stale: 342 | 343 | 1. **Regular Reviews**: Schedule quarterly architecture reviews 344 | 2. **Change Documentation**: Update immediately when making changes 345 | 3. **Version Control**: Track architecture changes in Git 346 | 4. **Team Alignment**: Ensure all team members update documentation 347 | 348 | ## 📞 Need Help? 349 | 350 | - **Setup Issues**: See [Troubleshooting Guide](troubleshooting.md) 351 | - **Rule Management**: Check [Custom Rules](custom-rules.md) 352 | - **Workflow Integration**: Read [Workflow System](workflow-system.md) 353 | 354 | --- 355 | 356 | *The architecture rule ensures your AI assistant becomes an expert in your specific system architecture, leading to more consistent and thoughtful architectural decisions.* -------------------------------------------------------------------------------- /examples/frontend-react-typescript/README.md: -------------------------------------------------------------------------------- 1 | # 🎯 React TypeScript Example 2 | 3 | This example demonstrates how to use the Cursor Rule Framework with a React TypeScript application. It showcases modern React development patterns, component architecture, and testing strategies. 4 | 5 | ## 🚀 Quick Start 6 | 7 | ### 1. **Copy Rules to Your Project** 8 | ```bash 9 | # Copy cursor rules from this example 10 | cp -r .cursor/ /path/to/your/react-project/ 11 | 12 | # Or start a new project with this structure 13 | npx create-react-app my-app --template typescript 14 | cd my-app 15 | cp -r /path/to/cursor-rule-framework/examples/frontend-react-typescript/.cursor/ . 16 | ``` 17 | 18 | ### 2. **Install User Rules Template** ⚠️ **CRITICAL** 19 | ```bash 20 | # MUST DO: Install the framework's user rules template 21 | # This enables AI-driven workflow with epic integration 22 | 23 | # 1. Copy template content 24 | code .cursor/rules/user-rules-template.mdc 25 | 26 | # 2. Cursor IDE: Settings → Features → Rules for AI → User Rules 27 | # 3. Paste entire template content and save 28 | # 4. Restart Cursor IDE 29 | ``` 30 | 31 | ### 3. **Open in Cursor IDE** 32 | ```bash 33 | cursor . 34 | 35 | # Verify rules are loaded 36 | # CMD/Ctrl + Shift + P → "Cursor: Rules" 37 | ``` 38 | 39 | ### 4. **Customize Project Configuration** 40 | Edit `.cursor/rules/project-config.mdc`: 41 | ```yaml 42 | ## Project Goal 43 | Build a scalable React TypeScript application with modern development practices 44 | 45 | ## Tech Stack 46 | - **Language(s):** TypeScript 47 | - **Framework(s):** React 18, Vite 48 | - **Build / Tooling:** Vite, Vitest, ESLint, Prettier 49 | - **Monorepo Structure:** Single package React application 50 | ``` 51 | 52 | ## 📋 What's Included 53 | 54 | ### **Cursor Rules** 55 | - **`cursor-rules-management.mdc`** - Framework management and metadata preservation 56 | - **`project-config.mdc`** - React TypeScript specific configuration 57 | - **`frontend-react-rules.mdc`** - React component development guidelines 58 | - **`testing-rules.mdc`** - Testing strategies for React components 59 | - **`workflow-state.mdc`** - Development workflow management 60 | - **`epics.mdc`** - Feature planning and tracking 61 | 62 | ### **Development Patterns** 63 | - **Component Architecture**: Functional components with hooks 64 | - **State Management**: Context API and custom hooks 65 | - **Styling**: CSS Modules with TypeScript support 66 | - **Testing**: Vitest with React Testing Library 67 | - **Code Quality**: ESLint, Prettier, TypeScript strict mode 68 | 69 | ## 🏗️ Project Structure 70 | 71 | ``` 72 | src/ 73 | ├── components/ 74 | │ ├── ui/ # Reusable UI components 75 | │ ├── forms/ # Form components 76 | │ └── layout/ # Layout components 77 | ├── hooks/ # Custom React hooks 78 | ├── contexts/ # React contexts 79 | ├── utils/ # Utility functions 80 | ├── types/ # TypeScript type definitions 81 | ├── __tests__/ # Test files 82 | └── App.tsx # Main application component 83 | ``` 84 | 85 | ## 📖 Rule Highlights 86 | 87 | ### **Component Development Rules** 88 | 89 | #### **Naming Conventions** 90 | ```typescript 91 | // ✅ Good - PascalCase for components 92 | export default function UserProfile({ userId }: Props) { 93 | return
User profile
94 | } 95 | 96 | // ✅ Good - File name matches component 97 | // File: UserProfile.tsx 98 | 99 | // ❌ Bad - camelCase for components 100 | export function userProfile() { 101 | return
content
102 | } 103 | ``` 104 | 105 | #### **Props Interface Pattern** 106 | ```typescript 107 | // ✅ Good - Explicit props interface 108 | interface UserProfileProps { 109 | userId: string 110 | onUpdate?: (user: User) => void 111 | } 112 | 113 | export default function UserProfile({ userId, onUpdate }: UserProfileProps) { 114 | // Component implementation 115 | } 116 | ``` 117 | 118 | #### **Custom Hooks Pattern** 119 | ```typescript 120 | // ✅ Good - Custom hook with proper naming 121 | function useUserProfile(userId: string) { 122 | const [user, setUser] = useState(null) 123 | const [loading, setLoading] = useState(true) 124 | 125 | // Hook implementation 126 | 127 | return { user, loading, updateUser } 128 | } 129 | ``` 130 | 131 | ### **Testing Rules** 132 | 133 | #### **Component Testing Pattern** 134 | ```typescript 135 | // ✅ Good - Comprehensive component test 136 | import { render, screen, fireEvent } from '@testing-library/react' 137 | import UserProfile from '../UserProfile' 138 | 139 | describe('UserProfile', () => { 140 | it('displays user information correctly', () => { 141 | render() 142 | 143 | expect(screen.getByText('User Profile')).toBeInTheDocument() 144 | expect(screen.getByRole('button', { name: 'Edit' })).toBeInTheDocument() 145 | }) 146 | 147 | it('calls onUpdate when form is submitted', () => { 148 | const mockUpdate = vi.fn() 149 | render() 150 | 151 | fireEvent.click(screen.getByRole('button', { name: 'Save' })) 152 | expect(mockUpdate).toHaveBeenCalledWith(expect.any(Object)) 153 | }) 154 | }) 155 | ``` 156 | 157 | ### **State Management Rules** 158 | 159 | #### **Context Pattern** 160 | ```typescript 161 | // ✅ Good - Context with provider pattern 162 | interface UserContextValue { 163 | user: User | null 164 | login: (email: string, password: string) => Promise 165 | logout: () => void 166 | } 167 | 168 | const UserContext = createContext(undefined) 169 | 170 | export function UserProvider({ children }: { children: ReactNode }) { 171 | // Context implementation 172 | 173 | return ( 174 | 175 | {children} 176 | 177 | ) 178 | } 179 | 180 | export function useUser() { 181 | const context = useContext(UserContext) 182 | if (!context) { 183 | throw new Error('useUser must be used within UserProvider') 184 | } 185 | return context 186 | } 187 | ``` 188 | 189 | ## 🛠️ Development Workflow 190 | 191 | ### **AI-Driven Epic and Architecture Integration** 192 | ```bash 193 | # Start epic work with natural language 194 | "Plan an epic for user authentication with login, registration, and password reset" 195 | 196 | # Work on specific epic steps 197 | "Start working on the login component from the user authentication epic" 198 | 199 | # Update progress naturally 200 | "Update the login component progress to 75%, core functionality complete" 201 | 202 | # AI automatically: 203 | # - Creates and manages epics in epics.mdc 204 | # - Integrates epic context into workflow 205 | # - Validates against existing architecture patterns 206 | # - Updates architecture.mdc with new React patterns 207 | # - Updates progress as work completes 208 | ``` 209 | 210 | ### **Blueprint Phase** 211 | ```bash 212 | # AI automatically includes epic context when available 213 | # For epic work: Requirements and acceptance criteria included 214 | # For standalone work: Standard planning process 215 | 216 | # Architecture validation happens automatically: 217 | # - Reviews existing React patterns in architecture.mdc 218 | # - Validates component design against established conventions 219 | # - Plans architecture updates for new patterns 220 | 221 | # Define interfaces and types first 222 | # AI uses epic requirements and architecture patterns to guide component design 223 | ``` 224 | 225 | ### **Construct Phase** 226 | ```bash 227 | # AI enforces naming conventions and patterns from rules 228 | # Implements exactly what was planned in blueprint 229 | # Updates architecture.mdc with new React patterns and decisions 230 | # Updates epic progress automatically upon completion 231 | ``` 232 | 233 | ### **Validate Phase** 234 | ```bash 235 | # Automated validation 236 | npm test && npm run type-check && npm run lint 237 | 238 | # Epic progress automatically updated to 100% when complete 239 | ``` 240 | 241 | ## 🧪 Testing Strategy 242 | 243 | ### **Component Testing** 244 | - **Unit Tests**: Individual component behavior 245 | - **Integration Tests**: Component interaction 246 | - **Accessibility Tests**: Screen reader compatibility 247 | - **Visual Tests**: Component appearance 248 | 249 | ### **Hook Testing** 250 | ```typescript 251 | // ✅ Good - Custom hook testing 252 | import { renderHook, act } from '@testing-library/react' 253 | import { useUserProfile } from '../useUserProfile' 254 | 255 | describe('useUserProfile', () => { 256 | it('loads user data on mount', async () => { 257 | const { result } = renderHook(() => useUserProfile('123')) 258 | 259 | expect(result.current.loading).toBe(true) 260 | 261 | await act(async () => { 262 | await waitFor(() => { 263 | expect(result.current.loading).toBe(false) 264 | expect(result.current.user).toBeDefined() 265 | }) 266 | }) 267 | }) 268 | }) 269 | ``` 270 | 271 | ## 📚 Learning Resources 272 | 273 | ### **React Patterns Covered** 274 | 1. **Functional Components** - Modern React development 275 | 2. **Custom Hooks** - Reusable state logic 276 | 3. **Context API** - Global state management 277 | 4. **Error Boundaries** - Error handling patterns 278 | 5. **Suspense** - Loading state management 279 | 280 | ### **TypeScript Integration** 281 | 1. **Component Props** - Type-safe props interfaces 282 | 2. **Event Handlers** - Typed event handling 283 | 3. **Refs** - Type-safe ref usage 284 | 4. **Generic Components** - Reusable typed components 285 | 286 | ### **Testing Best Practices** 287 | 1. **Testing Library** - User-centric testing 288 | 2. **Mock Strategies** - Effective mocking patterns 289 | 3. **Async Testing** - Testing asynchronous code 290 | 4. **Accessibility Testing** - Inclusive design validation 291 | 292 | ## 🚨 Common Issues & Solutions 293 | 294 | ### **Rules Not Appearing** 295 | ```bash 296 | # Check file location 297 | ls -la .cursor/rules/ 298 | 299 | # Verify metadata format 300 | head -10 .cursor/rules/frontend-react-rules.mdc 301 | ``` 302 | 303 | ### **TypeScript Errors** 304 | ```bash 305 | # Clear TypeScript cache 306 | rm -rf node_modules/.cache 307 | 308 | # Restart TypeScript server in Cursor 309 | # CMD/Ctrl + Shift + P → "TypeScript: Restart TS Server" 310 | ``` 311 | 312 | ### **Testing Issues** 313 | ```bash 314 | # Clear test cache 315 | npm test -- --clearCache 316 | 317 | # Run tests in watch mode 318 | npm test -- --watch 319 | ``` 320 | 321 | ## 🔧 Customization 322 | 323 | ### **Adding New Component Types** 324 | 1. Update `frontend-react-rules.mdc` 325 | 2. Add glob patterns for new file types 326 | 3. Define naming conventions 327 | 4. Add testing requirements 328 | 329 | ### **Integration with Design System** 330 | 1. Create design system rules 331 | 2. Add component validation 332 | 3. Define styling patterns 333 | 4. Include accessibility requirements 334 | 335 | ### **State Management Alternatives** 336 | - **Redux Toolkit**: Add Redux-specific rules 337 | - **Zustand**: Create Zustand pattern rules 338 | - **Recoil**: Define Recoil atom patterns 339 | 340 | ## 📈 Next Steps 341 | 342 | 1. **Explore Advanced Patterns**: Check out the [Full-Stack SaaS](../fullstack-saas-starter/) example 343 | 2. **Add More Rules**: Create domain-specific rules for your business logic 344 | 3. **Team Integration**: Share rules with your development team 345 | 4. **Continuous Improvement**: Update rules based on code review feedback 346 | 347 | ## 📞 Need Help? 348 | 349 | - **React Issues**: Check [React documentation](https://react.dev/) 350 | - **TypeScript Issues**: See [TypeScript handbook](https://www.typescriptlang.org/docs/) 351 | - **Testing Issues**: Visit [Testing Library docs](https://testing-library.com/) 352 | - **Framework Issues**: See main [Documentation](../../docs/README.md) 353 | 354 | --- 355 | 356 | **Ready to build?** Open this example in Cursor IDE and start developing with AI-powered assistance! 357 | 358 | *This example demonstrates production-ready React TypeScript patterns. Customize the rules to match your team's preferences and project requirements.* -------------------------------------------------------------------------------- /scripts/validate-docs.js: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | const fs = require('fs'); 4 | const path = require('path'); 5 | 6 | /** 7 | * Validates documentation files for completeness and quality 8 | */ 9 | class DocumentationValidator { 10 | constructor() { 11 | this.errors = []; 12 | this.warnings = []; 13 | this.validatedFiles = 0; 14 | this.linksToCheck = new Set(); 15 | } 16 | 17 | /** 18 | * Validate all documentation 19 | */ 20 | async validateAll() { 21 | console.log('🎯 Cursor Rule Framework - Documentation Validator'); 22 | console.log('===================================================\n'); 23 | 24 | // Validate core files 25 | await this.validateCoreFiles(); 26 | 27 | // Validate docs directory 28 | await this.validateDocsDirectory(); 29 | 30 | // Validate examples 31 | await this.validateExamplesDirectory(); 32 | 33 | // Check for broken internal links 34 | await this.validateInternalLinks(); 35 | 36 | return this.printSummary(); 37 | } 38 | 39 | /** 40 | * Validate core documentation files 41 | */ 42 | async validateCoreFiles() { 43 | const coreFiles = [ 44 | 'README.md', 45 | 'CHANGELOG.md', 46 | 'CONTRIBUTING.md', 47 | 'CODE_OF_CONDUCT.md', 48 | 'LICENSE' 49 | ]; 50 | 51 | console.log('📋 Validating core files...\n'); 52 | 53 | for (const file of coreFiles) { 54 | if (fs.existsSync(file)) { 55 | await this.validateFile(file); 56 | } else { 57 | this.addError('Core Files', `Missing required file: ${file}`); 58 | } 59 | } 60 | } 61 | 62 | /** 63 | * Validate docs directory 64 | */ 65 | async validateDocsDirectory() { 66 | const docsDir = 'docs'; 67 | 68 | console.log('📚 Validating docs directory...\n'); 69 | 70 | if (!fs.existsSync(docsDir)) { 71 | this.addError('Documentation', 'Missing docs directory'); 72 | return; 73 | } 74 | 75 | const docFiles = this.getMarkdownFiles(docsDir); 76 | for (const file of docFiles) { 77 | await this.validateFile(file); 78 | } 79 | 80 | // Check for required documentation 81 | const requiredDocs = [ 82 | 'docs/README.md', 83 | 'docs/getting-started.md', 84 | 'docs/rule-organization.md' 85 | ]; 86 | 87 | for (const doc of requiredDocs) { 88 | if (!fs.existsSync(doc)) { 89 | this.addWarning('Documentation', `Recommended doc missing: ${doc}`); 90 | } 91 | } 92 | } 93 | 94 | /** 95 | * Validate examples directory 96 | */ 97 | async validateExamplesDirectory() { 98 | const examplesDir = 'examples'; 99 | 100 | console.log('🛠️ Validating examples directory...\n'); 101 | 102 | if (!fs.existsSync(examplesDir)) { 103 | this.addWarning('Examples', 'Missing examples directory'); 104 | return; 105 | } 106 | 107 | // Check each example has a README 108 | const examples = fs.readdirSync(examplesDir) 109 | .filter(item => fs.statSync(path.join(examplesDir, item)).isDirectory()); 110 | 111 | for (const example of examples) { 112 | const readmePath = path.join(examplesDir, example, 'README.md'); 113 | if (!fs.existsSync(readmePath)) { 114 | this.addWarning('Examples', `Example ${example} missing README.md`); 115 | } else { 116 | await this.validateFile(readmePath); 117 | } 118 | } 119 | } 120 | 121 | /** 122 | * Validate a single file 123 | */ 124 | async validateFile(filePath) { 125 | try { 126 | const content = fs.readFileSync(filePath, 'utf8'); 127 | const fileName = path.basename(filePath); 128 | 129 | console.log(`🔍 Validating ${fileName}...`); 130 | 131 | // Basic checks 132 | if (content.length === 0) { 133 | this.addError(fileName, 'File is empty'); 134 | return; 135 | } 136 | 137 | // Markdown-specific validation 138 | if (filePath.endsWith('.md')) { 139 | this.validateMarkdown(fileName, content); 140 | } 141 | 142 | // Special validations for specific files 143 | if (fileName === 'README.md') { 144 | this.validateReadme(fileName, content); 145 | } else if (fileName === 'CHANGELOG.md') { 146 | this.validateChangelog(fileName, content); 147 | } else if (fileName === 'CONTRIBUTING.md') { 148 | this.validateContributing(fileName, content); 149 | } 150 | 151 | this.validatedFiles++; 152 | console.log(`✅ ${fileName} is valid`); 153 | 154 | } catch (error) { 155 | this.addError(path.basename(filePath), `Failed to read file: ${error.message}`); 156 | } 157 | } 158 | 159 | /** 160 | * Validate markdown content 161 | */ 162 | validateMarkdown(fileName, content) { 163 | const lines = content.split('\n'); 164 | let inCodeBlock = false; 165 | let hasHeading = false; 166 | 167 | for (let i = 0; i < lines.length; i++) { 168 | const line = lines[i]; 169 | const lineNum = i + 1; 170 | 171 | // Track code blocks 172 | if (line.trim().startsWith('```')) { 173 | inCodeBlock = !inCodeBlock; 174 | } 175 | 176 | // Check for headings 177 | if (line.trim().startsWith('#')) { 178 | hasHeading = true; 179 | } 180 | 181 | // Check for broken markdown 182 | if (!inCodeBlock) { 183 | // Unbalanced backticks 184 | const backticks = (line.match(/`/g) || []).length; 185 | if (backticks % 2 !== 0) { 186 | this.addWarning(fileName, `Line ${lineNum}: Unbalanced backticks`); 187 | } 188 | 189 | // Extract links for validation 190 | const linkRegex = /\[([^\]]+)\]\(([^)]+)\)/g; 191 | let match; 192 | while ((match = linkRegex.exec(line)) !== null) { 193 | const linkUrl = match[2]; 194 | this.linksToCheck.add({ file: fileName, url: linkUrl, line: lineNum }); 195 | } 196 | } 197 | } 198 | 199 | if (inCodeBlock) { 200 | this.addError(fileName, 'Unclosed code block'); 201 | } 202 | 203 | if (!hasHeading && content.length > 100) { 204 | this.addWarning(fileName, 'Document should have at least one heading'); 205 | } 206 | 207 | // Check for very short content (unless it's a placeholder) 208 | if (content.length < 50 && !content.includes('TODO') && !content.includes('placeholder')) { 209 | this.addWarning(fileName, 'Document content is very short'); 210 | } 211 | } 212 | 213 | /** 214 | * Validate README.md specifically 215 | */ 216 | validateReadme(fileName, content) { 217 | const requiredSections = [ 218 | /^#\s+.*(?:cursor|rule|framework)/i, // Title with keywords 219 | /installation|getting started|quick start/i, 220 | /usage|how to|examples/i, 221 | /contributing/i, 222 | /license/i 223 | ]; 224 | 225 | for (let i = 0; i < requiredSections.length; i++) { 226 | if (!requiredSections[i].test(content)) { 227 | const sectionNames = [ 228 | 'Title with keywords (Cursor, Rule, Framework)', 229 | 'Installation/Getting Started section', 230 | 'Usage/Examples section', 231 | 'Contributing section', 232 | 'License section' 233 | ]; 234 | this.addWarning(fileName, `Missing recommended section: ${sectionNames[i]}`); 235 | } 236 | } 237 | 238 | // Check for badges (common in open source READMEs) 239 | if (!content.includes('![') && !content.includes('[![')) { 240 | this.addWarning(fileName, 'Consider adding badges (build status, license, etc.)'); 241 | } 242 | } 243 | 244 | /** 245 | * Validate CHANGELOG.md specifically 246 | */ 247 | validateChangelog(fileName, content) { 248 | // Check for Keep a Changelog format 249 | if (!content.includes('Keep a Changelog')) { 250 | this.addWarning(fileName, 'Consider following Keep a Changelog format'); 251 | } 252 | 253 | // Check for semantic versioning 254 | if (!content.includes('Semantic Versioning')) { 255 | this.addWarning(fileName, 'Consider mentioning Semantic Versioning adherence'); 256 | } 257 | 258 | // Check for version entries 259 | const versionRegex = /##\s+\[\d+\.\d+\.\d+\]/; 260 | if (!versionRegex.test(content)) { 261 | this.addWarning(fileName, 'No version entries found'); 262 | } 263 | 264 | // Check for Unreleased section 265 | if (!content.includes('[Unreleased]')) { 266 | this.addWarning(fileName, 'Consider adding an [Unreleased] section for upcoming changes'); 267 | } 268 | } 269 | 270 | /** 271 | * Validate CONTRIBUTING.md specifically 272 | */ 273 | validateContributing(fileName, content) { 274 | const requiredSections = [ 275 | /getting started|development setup/i, 276 | /pull request|contribution process/i, 277 | /issue|bug report/i, 278 | /code of conduct/i 279 | ]; 280 | 281 | const sectionNames = [ 282 | 'Development setup section', 283 | 'Pull request process section', 284 | 'Issue reporting section', 285 | 'Code of conduct reference' 286 | ]; 287 | 288 | for (let i = 0; i < requiredSections.length; i++) { 289 | if (!requiredSections[i].test(content)) { 290 | this.addWarning(fileName, `Consider adding: ${sectionNames[i]}`); 291 | } 292 | } 293 | } 294 | 295 | /** 296 | * Validate internal links 297 | */ 298 | async validateInternalLinks() { 299 | console.log('🔗 Validating internal links...\n'); 300 | 301 | for (const link of this.linksToCheck) { 302 | // Skip external links 303 | if (link.url.startsWith('http://') || link.url.startsWith('https://')) { 304 | continue; 305 | } 306 | 307 | // Skip mailto and other protocol links 308 | if (link.url.includes(':')) { 309 | continue; 310 | } 311 | 312 | // Check if file exists 313 | let targetPath = link.url; 314 | 315 | // Handle relative paths 316 | if (!path.isAbsolute(targetPath)) { 317 | const linkDir = path.dirname(link.file); 318 | targetPath = path.resolve(linkDir, link.url); 319 | } 320 | 321 | // Remove fragment identifiers for file existence check 322 | const cleanPath = targetPath.split('#')[0]; 323 | 324 | if (!fs.existsSync(cleanPath)) { 325 | this.addError(link.file, `Broken link on line ${link.line}: ${link.url}`); 326 | } 327 | } 328 | } 329 | 330 | /** 331 | * Get all markdown files in a directory recursively 332 | */ 333 | getMarkdownFiles(dir) { 334 | const files = []; 335 | 336 | function scanDir(currentDir) { 337 | const items = fs.readdirSync(currentDir); 338 | 339 | for (const item of items) { 340 | const fullPath = path.join(currentDir, item); 341 | const stat = fs.statSync(fullPath); 342 | 343 | if (stat.isDirectory()) { 344 | scanDir(fullPath); 345 | } else if (item.endsWith('.md')) { 346 | files.push(fullPath); 347 | } 348 | } 349 | } 350 | 351 | scanDir(dir); 352 | return files; 353 | } 354 | 355 | /** 356 | * Add an error 357 | */ 358 | addError(fileName, message) { 359 | this.errors.push({ file: fileName, message, type: 'error' }); 360 | console.log(`❌ ${fileName}: ${message}`); 361 | } 362 | 363 | /** 364 | * Add a warning 365 | */ 366 | addWarning(fileName, message) { 367 | this.warnings.push({ file: fileName, message, type: 'warning' }); 368 | console.log(`⚠️ ${fileName}: ${message}`); 369 | } 370 | 371 | /** 372 | * Print validation summary 373 | */ 374 | printSummary() { 375 | console.log('\n📊 Documentation Validation Summary'); 376 | console.log('==================================='); 377 | console.log(`Files validated: ${this.validatedFiles}`); 378 | console.log(`Links checked: ${this.linksToCheck.size}`); 379 | console.log(`Errors: ${this.errors.length}`); 380 | console.log(`Warnings: ${this.warnings.length}`); 381 | 382 | if (this.errors.length === 0 && this.warnings.length === 0) { 383 | console.log('🎉 All documentation is valid!'); 384 | return true; 385 | } 386 | 387 | if (this.errors.length > 0) { 388 | console.log('\n❌ Errors (must be fixed):'); 389 | this.errors.forEach(err => { 390 | console.log(` • ${err.file}: ${err.message}`); 391 | }); 392 | } 393 | 394 | if (this.warnings.length > 0) { 395 | console.log('\n⚠️ Warnings (recommended improvements):'); 396 | this.warnings.forEach(warn => { 397 | console.log(` • ${warn.file}: ${warn.message}`); 398 | }); 399 | } 400 | 401 | return this.errors.length === 0; 402 | } 403 | } 404 | 405 | /** 406 | * Main execution 407 | */ 408 | async function main() { 409 | const validator = new DocumentationValidator(); 410 | const success = await validator.validateAll(); 411 | process.exit(success ? 0 : 1); 412 | } 413 | 414 | // Run if called directly 415 | if (require.main === module) { 416 | main().catch(error => { 417 | console.error('❌ Validation failed:', error); 418 | process.exit(1); 419 | }); 420 | } 421 | 422 | module.exports = { DocumentationValidator }; -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | # ❓ Frequently Asked Questions 2 | 3 | Common questions and answers about the Cursor Rule Framework. 4 | 5 | ## 🚀 Getting Started 6 | 7 | ### **Q: What is the Cursor Rule Framework?** 8 | **A:** The Cursor Rule Framework is a system for creating structured AI development workflows using cursor rules. It provides a methodology for consistent, AI-driven development with three core components: 9 | - **Rules**: Structured guidelines that AI assistants follow 10 | - **Workflow**: Blueprint → Construct → Validate development phases 11 | - **Epic Planning**: Managing large initiatives with AI assistance 12 | 13 | ### **Q: Do I need Cursor IDE to use this framework?** 14 | **A:** Yes, the framework is specifically designed for Cursor IDE's rule system. While the concepts could be adapted to other AI assistants, the full functionality requires Cursor IDE and its MDC rule format. 15 | 16 | ### **Q: What's the difference between this and regular AI coding assistants?** 17 | **A:** Regular AI assistants provide general help without context about your specific project patterns. The Cursor Rule Framework provides: 18 | - **Project-specific context** through rules 19 | - **Consistent patterns** across your team 20 | - **Structured workflow** for complex development 21 | - **Living documentation** that evolves with your code 22 | - **Epic-level planning** for large initiatives 23 | 24 | ### **Q: How long does it take to set up?** 25 | **A:** Basic setup takes 5-10 minutes. Full team adoption typically takes 2-4 weeks: 26 | - **Day 1**: Install Cursor IDE and copy user rules template 27 | - **Week 1**: Create project-specific rules and architecture documentation 28 | - **Week 2-4**: Team adoption and workflow integration 29 | 30 | ## 🛠️ Setup and Configuration 31 | 32 | ### **Q: I copied the user rules template but AI doesn't seem to follow my project rules. Why?** 33 | **A:** Check these common issues: 34 | 1. **Rule location**: Ensure rules are in `.cursor/rules/` directory (not root level) 35 | 2. **File extension**: Rules must use `.mdc` extension, not `.md` 36 | 3. **YAML frontmatter**: Each rule file needs proper metadata header 37 | 4. **Cursor restart**: Restart Cursor IDE after adding new rules 38 | 39 | ### **Q: What's the difference between user rules and project rules?** 40 | **A:** 41 | - **User rules** (in Cursor settings): Apply to all your projects, contain the framework methodology 42 | - **Project rules** (in `.cursor/rules/`): Specific to one project, contain project patterns and architecture 43 | 44 | ### **Q: Can I use this framework with an existing project?** 45 | **A:** Yes! See our [Migration Guide](migration-guide.md) for step-by-step instructions. The framework is designed to work with existing codebases and can be adopted gradually. 46 | 47 | ### **Q: Which files are required in `.cursor/rules/`?** 48 | **A:** Core required files: 49 | - `cursor-rules-management.mdc` - Rule management policies 50 | - `project-config.mdc` - Project configuration and tech stack 51 | - `workflow-state.mdc` - Development workflow state 52 | - `epics.mdc` - Epic planning and tracking 53 | - `architecture.mdc` - Architecture documentation and decisions 54 | 55 | Optional but recommended: 56 | - Technology-specific rule files (e.g., `react-patterns.mdc`) 57 | - Domain-specific rules (e.g., `authentication.mdc`) 58 | 59 | ## 📋 Workflow System 60 | 61 | ### **Q: Do I have to use the Blueprint → Construct → Validate workflow for every small change?** 62 | **A:** No. Use the full workflow for: 63 | - **New features** (any size) 64 | - **Architectural changes** 65 | - **Complex bug fixes** 66 | - **Epic-related work** 67 | 68 | For simple bug fixes or typos, you can work directly without the formal workflow. 69 | 70 | ### **Q: What if I need to change the plan during the Construct phase?** 71 | **A:** Minor adjustments are fine, but for major changes: 72 | 1. **Return to Blueprint phase** 73 | 2. **Update the plan** with the new approach 74 | 3. **Get approval** if working with a team 75 | 4. **Continue with Construct** using the updated plan 76 | 77 | ### **Q: The AI isn't following the workflow phases. What should I do?** 78 | **A:** Ensure you have the user rules template installed correctly. The workflow behavior comes from the user rules, not project rules. If it's still not working: 79 | 1. Check Cursor IDE rule settings 80 | 2. Restart Cursor IDE 81 | 3. Try explicit phase commands: "Enter Blueprint phase for user authentication feature" 82 | 83 | ### **Q: How do I know when to move between workflow phases?** 84 | **A:** 85 | - **Blueprint → Construct**: When you have a detailed, approved plan 86 | - **Construct → Validate**: When implementation is complete according to the plan 87 | - **Validate → Complete**: When all tests pass and quality gates are met 88 | - **Any phase → Blueprint**: When you discover the current approach won't work 89 | 90 | ## 📈 Epic Planning 91 | 92 | ### **Q: What's the difference between epics, phases, and steps?** 93 | **A:** 94 | - **Epic**: Large initiative (e.g., "User Management System") 95 | - **Phase**: Major milestone within an epic (e.g., "Authentication Implementation") 96 | - **Step**: Individual feature within a phase (e.g., "Login Component") 97 | 98 | ### **Q: How many epics should I have active at once?** 99 | **A:** Maximum 2-3 active epics. This keeps AI context manageable and ensures focused development. Archive completed epics older than 6 months. 100 | 101 | ### **Q: Can I work on something that's not part of an epic?** 102 | **A:** Yes! Not all work needs to be epic-related. Use epics for: 103 | - **Large features** that take weeks/months 104 | - **Major architectural changes** 105 | - **Cross-team initiatives** 106 | 107 | Standalone work like bug fixes, small improvements, or experimental features doesn't need epic context. 108 | 109 | ### **Q: How does epic progress get updated?** 110 | **A:** Epic progress updates happen automatically: 111 | 1. **During workflow completion**: AI updates epic step status when workflow finishes 112 | 2. **Manual updates**: You can manually update progress: "Update login component progress to 75%" 113 | 3. **Natural language**: Tell AI about progress and it updates the epic 114 | 115 | ### **Q: What if my epic scope changes significantly?** 116 | **A:** Update the epic structure: 117 | 1. **Add new phases/steps** as needed 118 | 2. **Remove or modify** outdated steps 119 | 3. **Update epic goal** if the objective changed 120 | 4. **Document** the scope change in epic notes 121 | 122 | ## 🏗️ Architecture Integration 123 | 124 | ### **Q: What's architecture.mdc and why is it important?** 125 | **A:** Architecture.mdc is your living architecture documentation. It: 126 | - **Guides AI decisions** during development 127 | - **Maintains consistency** across your codebase 128 | - **Documents patterns** automatically as you build 129 | - **Prevents architectural drift** 130 | - **Helps onboard** new team members 131 | 132 | ### **Q: Do I need to manually update architecture.mdc?** 133 | **A:** No! The AI updates it automatically during the Construct phase. You should: 134 | - **Review changes** periodically 135 | - **Approve major** architectural decisions 136 | - **Resolve conflicts** if multiple people update simultaneously 137 | 138 | ### **Q: What if my current architecture is messy or inconsistent?** 139 | **A:** Start by documenting the current state honestly: 140 | 1. **Document what exists** (even if it's inconsistent) 141 | 2. **Plan improvements** as separate epics 142 | 3. **Evolve gradually** rather than trying to fix everything at once 143 | 4. **Use the framework** to guide improvements over time 144 | 145 | ### **Q: How do I handle architecture conflicts between team members?** 146 | **A:** Architecture.mdc includes a collaboration protocol: 147 | 1. **Timestamp-based conflict resolution** (latest wins) 148 | 2. **Clear change attribution** (AI vs User updates) 149 | 3. **Regular architecture reviews** to align the team 150 | 4. **Document disagreements** as ADRs (Architecture Decision Records) 151 | 152 | ## 👥 Team Collaboration 153 | 154 | ### **Q: How do multiple developers use the same rules?** 155 | **A:** Rules are stored in your project repository (`.cursor/rules/`), so they're shared through version control: 156 | - **Commit rule changes** to your repository 157 | - **Pull updates** from teammates 158 | - **Merge conflicts** are handled like any other file 159 | - **Everyone gets the same** rule context 160 | 161 | ### **Q: What if team members have different rule preferences?** 162 | **A:** Focus on team consistency over individual preferences: 163 | - **Team rules** (in `.cursor/rules/`) apply to everyone 164 | - **Individual preferences** can be in personal user rules 165 | - **Discuss and agree** on team patterns 166 | - **Update rules** based on team feedback 167 | 168 | ### **Q: How do we handle rule updates and improvements?** 169 | **A:** Treat rules like code: 170 | - **Propose changes** through pull requests 171 | - **Test rule changes** before committing 172 | - **Document rule evolution** in commit messages 173 | - **Regular rule reviews** in team meetings 174 | 175 | ### **Q: What about onboarding new team members?** 176 | **A:** The framework significantly improves onboarding: 177 | 1. **New team members** get instant context through rules 178 | 2. **Architecture documentation** provides system overview 179 | 3. **Epic tracking** shows current work and priorities 180 | 4. **Consistent patterns** reduce learning curve 181 | 182 | ## 🐛 Troubleshooting 183 | 184 | ### **Q: AI is not following my rules. What's wrong?** 185 | **A:** Check in order: 186 | 1. **File location**: Rules in `.cursor/rules/` not root directory? 187 | 2. **File extension**: Using `.mdc` not `.md`? 188 | 3. **YAML frontmatter**: Proper metadata header? 189 | 4. **Cursor restart**: Restart IDE after rule changes 190 | 5. **Rule clarity**: Is the rule specific enough? 191 | 192 | ### **Q: Workflow state seems stuck or corrupted. How do I reset it?** 193 | **A:** Reset workflow state: 194 | ```bash 195 | # Clear current state 196 | echo '## State 197 | Phase: READY 198 | Status: READY 199 | CurrentItem: None 200 | 201 | ## Plan 202 | [No active plan] 203 | 204 | ## Items 205 | | id | description | status | 206 | |----|-------|------| 207 | 208 | ## Log 209 | [Workflow log will appear here]' > .cursor/rules/workflow-state.mdc 210 | ``` 211 | 212 | ### **Q: Epic progress isn't updating automatically. Why?** 213 | **A:** Check these conditions: 214 | 1. **Epic reference set**: Is `EpicReference` set in workflow state? 215 | 2. **Epic exists**: Does the referenced epic exist in epics.mdc? 216 | 3. **Step matches**: Does the workflow item match an epic step? 217 | 4. **Workflow completion**: Did you complete the Validate phase? 218 | 219 | ### **Q: Architecture.mdc is not being updated during development. What's missing?** 220 | **A:** Ensure: 221 | 1. **User rules template** is correctly installed 222 | 2. **Workflow phases** are being used (not direct implementation) 223 | 3. **Architecture changes** are actually being made 224 | 4. **RULE_ARCHITECTURE_UPDATE_01** is active in workflow-state.mdc 225 | 226 | ## 🎯 Best Practices 227 | 228 | ### **Q: What's the most important thing for framework success?** 229 | **A:** **Consistency**. The framework's value comes from: 230 | - **Everyone using** the same patterns 231 | - **Regular workflow usage** for all significant development 232 | - **Keeping documentation current** (which happens automatically) 233 | - **Team commitment** to the methodology 234 | 235 | ### **Q: How specific should rules be?** 236 | **A:** Be as specific as helpful, but not overly restrictive: 237 | - **Good**: "Use React functional components with TypeScript interfaces for props" 238 | - **Too vague**: "Write good React code" 239 | - **Too specific**: "All button components must have exactly 3 props named 'text', 'onClick', and 'variant'" 240 | 241 | ### **Q: Should we create rules for everything?** 242 | **A:** No. Focus on rules that: 243 | - **Solve real problems** your team faces 244 | - **Improve consistency** across the codebase 245 | - **Capture important patterns** unique to your project 246 | - **Save time** on repetitive decisions 247 | 248 | Avoid rules for things that are already well-established or obvious. 249 | 250 | ### **Q: How often should we review and update our rules?** 251 | **A:** Suggested schedule: 252 | - **Weekly**: Quick review of rule effectiveness 253 | - **Monthly**: Detailed rule review and improvements 254 | - **Quarterly**: Major rule restructuring if needed 255 | - **As needed**: When new patterns emerge or problems arise 256 | 257 | ## 💡 Advanced Usage 258 | 259 | ### **Q: Can I use this framework for non-web development?** 260 | **A:** Yes! The framework is technology-agnostic. Create rules for: 261 | - **Mobile development** (React Native, Flutter) 262 | - **Backend services** (any language/framework) 263 | - **DevOps and infrastructure** (Docker, Kubernetes) 264 | - **Data science** (Python, R, Jupyter) 265 | 266 | ### **Q: How do I customize the workflow for my team's needs?** 267 | **A:** The three-phase workflow is core to the framework, but you can: 268 | - **Add sub-phases** within each phase 269 | - **Customize validation criteria** in the Validate phase 270 | - **Add team-specific rules** for each phase 271 | - **Create custom epic templates** for different work types 272 | 273 | ### **Q: Can I integrate this with external tools?** 274 | **A:** The framework uses standard files (markdown, YAML) that can be integrated with: 275 | - **Project management tools** (parse epics for roadmap tracking) 276 | - **Documentation systems** (include architecture.mdc in docs) 277 | - **CI/CD pipelines** (validate rule compliance) 278 | - **Analytics tools** (track epic completion rates) 279 | 280 | --- 281 | 282 | **Still have questions?** Check our [Troubleshooting Guide](troubleshooting.md) or join the community discussions! -------------------------------------------------------------------------------- /.cursor/rules/epics.mdc: -------------------------------------------------------------------------------- 1 | --- 2 | description: Used when referred by @@EPIC or @@EPICS or when writing or completing any epic level of work or epic level of capabilities. 3 | globs: 4 | alwaysApply: false 5 | --- 6 | **Epic Planning & Tracking System** 7 | 8 | 9 | **Purpose**: Plan and track large initiatives using the hierarchy: EPIC GROUP → EPIC → PHASE → STEPS 10 | 11 | **Hierarchy Definitions**: 12 | - **EPIC GROUP**: Optional grouping of related epics 13 | - **EPIC**: Large collection of features/capabilities 14 | - **PHASE**: Major milestone within an epic 15 | - **STEP**: Individual feature within a phase 16 | 17 | **AI Usage Rules**: 18 | 1. **Epic Creation**: When user requests epic planning, create comprehensive plans here 19 | 2. **Architecture Integration**: Always consider architecture.mdc when planning epics and include architectural impact in epic steps 20 | 3. **No Execution**: Never execute epic work - that happens in workflow_state.mdc 21 | 4. **Natural Language Processing**: Translate user requests into epic context for workflow integration 22 | 5. **Progress Updates**: Update epic status when user reports progress or workflow completes 23 | 6. **Epic Search**: Search existing epics when user mentions epic work to set proper workflow context 24 | 25 | **Context Limits**: Maximum 3 active epics to maintain AI effectiveness 26 | 27 | **EPICS PLANS** 28 | 29 | 30 | ## EPIC PORTFOLIO STATUS 31 | 32 | ### Current Portfolio Summary 33 | - **Total Active Epics**: 0 (Max: 3) 34 | - **Completed Epics**: 0 35 | - **Blocked Epics**: 0 36 | - **Last Updated**: [Date when portfolio was last updated] 37 | 38 | ### Portfolio Limits 39 | **Max Active Epics**: 3 (to maintain AI context effectiveness) 40 | **Auto-Archive**: Completed epics older than 6 months 41 | 42 | ### Epic Status Legend 43 | - ✅ **COMPLETED**: All phases and steps finished 44 | - 🔄 **IN_PROGRESS**: Currently being worked on 45 | - ⏳ **PLANNED**: Planned but not yet started 46 | - 🚫 **BLOCKED**: Stopped due to dependencies or issues 47 | - ⏸️ **PAUSED**: Temporarily suspended 48 | - ❌ **CANCELLED**: No longer needed 49 | - 📦 **ARCHIVED**: Completed and archived for reference 50 | 51 | --- 52 | 53 | ## ACTIVE EPICS 54 | 55 | 56 | 57 | *No active epics currently planned. Use @EPIC or @EPICS to create new epic plans.* 58 | 59 | --- 60 | 61 | ## EPIC PROGRESS TRACKING 62 | 63 | 64 | 65 | ### Simplified Epic Template 66 | ``` 67 | ### EPIC: [Epic Name] 68 | **Status**: [PLANNED/IN_PROGRESS/BLOCKED/COMPLETED] 69 | **Priority**: [High/Medium/Low] 70 | **Started**: [Start date] 71 | **Target Completion**: [Target date] 72 | 73 | #### Goal 74 | [Clear business objective and user value] 75 | 76 | #### Success Criteria 77 | - [ ] [Measurable outcome 1] 78 | - [ ] [Measurable outcome 2] 79 | - [ ] [Measurable outcome 3] 80 | 81 | #### Dependencies & Blockers 82 | - [Current dependencies or blocking issues] 83 | 84 | #### PHASE 1: [Phase Name] - [STATUS_ICON] [STATUS] 85 | **Goal**: [Phase objective and deliverables] 86 | 87 | **Steps:** 88 | 1. **[Step Name]**: [What needs to be built/implemented] - [STATUS_ICON] [COMPLETION_%] 89 | - Key requirements: [2-3 critical requirements] 90 | - Acceptance criteria: [What defines "done"] 91 | - Architecture impact: [How this affects current architecture or introduces new patterns] 92 | - AI considerations: [Important context for AI execution] 93 | - Status: [PLANNED/IN_PROGRESS/COMPLETED] ([completion_%]) 94 | - Started: [Date when work began] 95 | - Last Updated: [Date of last progress] 96 | - Completed: [Date when step finished] 97 | - Notes: [Progress notes, decisions, blockers] 98 | 99 | 2. **[Step Name]**: [What needs to be built/implemented] - [STATUS_ICON] [COMPLETION_%] 100 | - Key requirements: [2-3 critical requirements] 101 | - Acceptance criteria: [What defines "done"] 102 | - AI considerations: [Important context for AI execution] 103 | - Status: [PLANNED/IN_PROGRESS/COMPLETED] ([completion_%]) 104 | - Started: [Date when work began] 105 | - Last Updated: [Date of last progress] 106 | - Completed: [Date when step finished] 107 | - Notes: [Progress notes, decisions, blockers] 108 | 109 | 3. **[Step Name]**: [What needs to be built/implemented] - [STATUS_ICON] [COMPLETION_%] 110 | - Key requirements: [2-3 critical requirements] 111 | - Acceptance criteria: [What defines "done"] 112 | - AI considerations: [Important context for AI execution] 113 | - Status: [PLANNED/IN_PROGRESS/COMPLETED] ([completion_%]) 114 | - Started: [Date when work began] 115 | - Last Updated: [Date of last progress] 116 | - Completed: [Date when step finished] 117 | - Notes: [Progress notes, decisions, blockers] 118 | 119 | #### PHASE 2: [Phase Name] - [STATUS_ICON] [STATUS] 120 | **Goal**: [Phase objective and deliverables] 121 | 122 | **Steps:** 123 | 1. **[Step Name]**: [What needs to be built/implemented] 124 | - Key requirements: [2-3 critical requirements] 125 | - Acceptance criteria: [What defines "done"] 126 | - AI considerations: [Important context for AI execution] 127 | 128 | 2. **[Step Name]**: [What needs to be built/implemented] 129 | - Key requirements: [2-3 critical requirements] 130 | - Acceptance criteria: [What defines "done"] 131 | - AI considerations: [Important context for AI execution] 132 | 133 | #### PHASE 3: [Phase Name] - [STATUS_ICON] [STATUS] 134 | **Goal**: [Phase objective and deliverables] 135 | 136 | **Steps:** 137 | 1. **[Step Name]**: [What needs to be built/implemented] 138 | - Key requirements: [2-3 critical requirements] 139 | - Acceptance criteria: [What defines "done"] 140 | - AI considerations: [Important context for AI execution] 141 | 142 | #### Notes 143 | - [Key decisions, scope changes, or important context] 144 | ``` 145 | 146 | ### **Example: User Management Epic with Workflow Integration** 147 | ``` 148 | ### EPIC: USER_MGMT_EPIC 149 | **Status**: IN_PROGRESS 150 | **Priority**: High 151 | **Started**: 2025-01-16 152 | **Target Completion**: 2025-02-28 153 | 154 | #### Goal 155 | Create comprehensive user management system with authentication and profiles 156 | 157 | #### Success Criteria 158 | - [ ] Users can register and authenticate securely 159 | - [ ] User profile management with real-time updates 160 | - [ ] Admin dashboard for user administration 161 | 162 | #### Dependencies & Blockers 163 | - Database schema completed ✅ 164 | - Authentication service selected (Clerk) ✅ 165 | 166 | #### PHASE 1: AUTHENTICATION_PHASE - 🔄 IN_PROGRESS 167 | **Goal**: Implement secure user authentication system 168 | 169 | **Steps:** 170 | 1. **REGISTRATION_COMPONENT_STEP**: Build user registration form - ✅ 100% 171 | - Key requirements: Email validation, password strength, GDPR compliance 172 | - Acceptance criteria: Form validates inputs, stores user securely, sends confirmation 173 | - Architecture impact: Establishes form validation patterns and authentication service integration 174 | - AI considerations: Use existing form patterns, integrate with Clerk 175 | - Status: COMPLETED (100%) 176 | - Started: 2025-01-16 177 | - Last Updated: 2025-01-18 178 | - Completed: 2025-01-18 179 | - Notes: Successfully integrated with Clerk, added custom validation rules 180 | 181 | 2. **LOGIN_COMPONENT_STEP**: Implement secure login system - 🔄 75% 182 | - Key requirements: Session management, rate limiting, remember me 183 | - Acceptance criteria: Users can login/logout, sessions persist, security headers 184 | - Architecture impact: Establishes session management patterns and security middleware 185 | - AI considerations: Follow OAuth patterns, secure cookie handling 186 | - Status: IN_PROGRESS (75%) 187 | - Started: 2025-01-18 188 | - Last Updated: 2025-01-20 189 | - Completed: [Not completed] 190 | - Notes: Core login working, implementing remember me functionality 191 | 192 | 3. **PASSWORD_RESET_STEP**: Build password reset flow - ⏳ 0% 193 | - Key requirements: Email verification, secure tokens, 1-hour expiration 194 | - Acceptance criteria: Users can reset via email, tokens expire properly 195 | - Architecture impact: Introduces email service integration and token management patterns 196 | - AI considerations: Use email service, implement secure token generation 197 | - Status: PLANNED (0%) 198 | - Started: [Not started] 199 | - Last Updated: [Not started] 200 | - Completed: [Not completed] 201 | - Notes: Waiting for login completion 202 | 203 | #### Notes 204 | - 2025-01-20: Login component 75% complete via workflow 205 | - 2025-01-18: Registration completed successfully, all tests passing 206 | - 2025-01-16: Epic created, authentication phase started 207 | ``` 208 | 209 | *Other progress tracking entries will appear here as epics are created and executed.* 210 | 211 | --- 212 | 213 | ## EPIC COMPLETION HISTORY 214 | 215 | 216 | 217 | 218 | *No completed epics yet. Completed epics will be listed here with completion date and key outcomes.* 219 | 220 | --- 221 | 222 | ## EPIC REPORTING AND RETROSPECTIVES 223 | 224 | ### Epic Status Summary (Manual Count) 225 | *Updated manually when reviewing epic portfolio* 226 | - **Current Active Epics**: [Count from Active Epics section] 227 | - **Total Completed Epics**: [Count from Completion History] 228 | - **Last Portfolio Review**: [Date of last manual review] 229 | 230 | ### Epic Retrospective Template 231 | *Used when completing epics to capture learnings* 232 | ``` 233 | ## Epic Retrospective: [Epic Name] 234 | 235 | ### Epic Summary 236 | - **Final Status**: [Completed/Cancelled with reason] 237 | - **Key Phases Completed**: [List major phases finished] 238 | - **Original vs Actual Scope**: [Any scope changes made] 239 | 240 | ### What Went Well 241 | - [Positive aspects of the epic execution] 242 | 243 | ### What Could Be Improved 244 | - [Areas for improvement in future epics] 245 | 246 | ### Lessons Learned 247 | - [Key learnings to apply to future epics] 248 | 249 | ### Recommendations 250 | - [Specific recommendations for future epic planning/execution] 251 | ``` 252 | 253 | ### Epic Maintenance Checklist 254 | *For occasional portfolio cleanup* 255 | - [ ] Review active epic statuses and update if needed 256 | - [ ] Check for epics that should be completed or cancelled 257 | - [ ] Archive completed epics older than 6 months 258 | - [ ] Ensure no more than 3 active epics 259 | - [ ] Update portfolio summary counts 260 | 261 | --- 262 | 263 | ## EPIC MANAGEMENT GUIDELINES 264 | 265 | ### Epic State Management 266 | **State Transitions**: 267 | ``` 268 | PLANNED → IN_PROGRESS → COMPLETED 269 | ↓ ↓ ↑ 270 | CANCELLED ← BLOCKED ← ─ ─ ┘ 271 | ↓ ↓ 272 | ARCHIVED ← PAUSED 273 | ``` 274 | 275 | ### Update Guidelines 276 | - **Automatic Updates**: Epic steps are updated automatically when workflow completes with epic reference 277 | - **Manual Updates**: Can manually update step progress and notes during development 278 | - **Phase Completion**: Phases automatically marked complete when all steps reach 100% 279 | - **Epic Completion**: Move completed epics to history section 280 | - **Context Management**: Archive epics older than 6 months 281 | 282 | ### Step Status Tracking 283 | - **Status Icons**: ⏳ PLANNED, 🔄 IN_PROGRESS, ✅ COMPLETED, 🚫 BLOCKED 284 | - **Completion Percentage**: 0% (planned) → 25%, 50%, 75% → 100% (completed) 285 | - **Progress Dates**: Track started, last updated, and completed dates 286 | - **Progress Notes**: Document decisions, blockers, and key developments 287 | 288 | ### Portfolio Management 289 | - **Max Active Epics**: Keep only 2-3 active epics to maintain AI context effectiveness 290 | - **New Epic Planning**: If at limit, complete or pause existing epics before adding new ones 291 | - **Epic Focus**: Use workflow-state.mdc for detailed step execution, epics.mdc for high-level tracking 292 | 293 | ### AI Epic Management Patterns 294 | 295 | #### **When User Requests Epic Work** 296 | 1. **Search existing epics**: Look for matching epic names or features 297 | 2. **Identify step context**: Find specific phase and step user is referencing 298 | 3. **Set workflow context**: Configure workflow state with epic reference 299 | 4. **Provide epic context**: Include step requirements during blueprint phase 300 | 301 | #### **When User Reports Progress** 302 | 1. **Find current work**: Identify which epic step user is working on 303 | 2. **Update step status**: Modify completion percentage and notes 304 | 3. **Update dates**: Set last updated timestamp 305 | 4. **Check phase completion**: Update phase status if all steps complete 306 | 307 | #### **When User Requests Epic Planning** 308 | 1. **Create new epic**: Use simplified template in ACTIVE EPICS section 309 | 2. **Structure phases**: Break down epic into 2-4 phases 310 | 3. **Detail steps**: Add 2-5 steps per phase with requirements and acceptance criteria 311 | 4. **Set realistic scope**: Ensure epic fits within 3-epic portfolio limit 312 | 313 | ### Realistic Expectations 314 | - Epic updates happen through AI interactions based on user prompts 315 | - AI manages epic file updates, users provide natural language instructions 316 | - Epic planning serves as AI memory and workflow integration context 317 | - Focus on AI-driven epic management rather than manual file editing 318 | 319 | --- 320 | 321 | ## EPIC PLANNING WORKSPACE 322 | 323 | 324 | 325 | *This section can be used for drafting and refining epic plans before moving them to the active section.* 326 | 327 | --- 328 | 329 | 330 | 331 | -------------------------------------------------------------------------------- /docs/rule-testing.md: -------------------------------------------------------------------------------- 1 | # 🧪 Rule Testing Guide 2 | 3 | This guide explains how to validate and test your cursor rules to ensure they work effectively with AI assistants and improve development productivity. 4 | 5 | ## 🎯 Testing Philosophy 6 | 7 | Rule testing in the Cursor Rule Framework focuses on: 8 | - **Behavioral Validation**: Does the AI follow the rule correctly? 9 | - **Productivity Impact**: Does the rule improve development efficiency? 10 | - **Integration Testing**: Do rules work well together? 11 | - **Real-World Validation**: Testing with actual development scenarios 12 | 13 | ## 🔬 Types of Rule Testing 14 | 15 | ### **1. Behavioral Testing** 16 | Verify that AI assistants correctly interpret and follow your rules. 17 | 18 | #### **Test Structure** 19 | ```bash 20 | # Test: AI follows component naming rules 21 | # Rule: React components must use PascalCase 22 | # Expected: AI suggests "UserProfile.tsx" not "userProfile.tsx" 23 | 24 | # Prompt for testing 25 | "Create a new React component for displaying user profile information" 26 | 27 | # Expected AI Response Indicators: 28 | ✅ Suggests "UserProfile.tsx" filename 29 | ✅ Uses PascalCase for component name 30 | ✅ Follows established component structure 31 | ✅ References the naming rule in explanation 32 | 33 | # Failure Indicators: 34 | ❌ Suggests camelCase or kebab-case naming 35 | ❌ Doesn't mention naming conventions 36 | ❌ Ignores component structure rules 37 | ``` 38 | 39 | ### **2. Workflow Integration Testing** 40 | Test rules within the three-phase workflow system. 41 | 42 | #### **Blueprint Phase Testing** 43 | ```bash 44 | # Test: Architecture rule integration in planning 45 | # Rule: All API endpoints must follow REST conventions 46 | 47 | # Test Prompt: 48 | "Plan a user management API endpoint for creating users" 49 | 50 | # Expected AI Behavior: 51 | ✅ Reviews architecture.mdc for existing API patterns 52 | ✅ Plans RESTful endpoint (POST /api/users) 53 | ✅ Includes proper HTTP status codes 54 | ✅ Plans validation and error handling 55 | ✅ References architectural constraints 56 | 57 | # Test Command: 58 | "Follow the blueprint → construct → validate workflow for this API endpoint" 59 | ``` 60 | 61 | #### **Construct Phase Testing** 62 | ```bash 63 | # Test: Rule adherence during implementation 64 | # Expected AI Behavior: 65 | ✅ Implements exactly what was planned 66 | ✅ Follows coding standards from rules 67 | ✅ Updates architecture.mdc if new patterns emerge 68 | ✅ Maintains epic progress if applicable 69 | ``` 70 | 71 | #### **Validate Phase Testing** 72 | ```bash 73 | # Test: Quality gate enforcement 74 | # Expected AI Behavior: 75 | ✅ Runs tests specified in project-config.mdc 76 | ✅ Validates against architectural rules 77 | ✅ Checks coding standards compliance 78 | ✅ Updates documentation if required 79 | ``` 80 | 81 | ### **3. Epic Integration Testing** 82 | Test rules work correctly with epic planning and tracking. 83 | 84 | #### **Epic Context Testing** 85 | ```bash 86 | # Test: Rules consider epic context 87 | # Setup: Active epic for user authentication 88 | 89 | # Test Prompt: 90 | "Work on the login component from the user authentication epic" 91 | 92 | # Expected AI Behavior: 93 | ✅ References epic requirements and acceptance criteria 94 | ✅ Applies relevant rules based on epic context 95 | ✅ Updates epic progress upon completion 96 | ✅ Maintains consistency with epic architecture decisions 97 | ``` 98 | 99 | ### **4. Rule Interaction Testing** 100 | Test how multiple rules work together. 101 | 102 | #### **Rule Precedence Testing** 103 | ```bash 104 | # Test: Global vs domain-specific rule interaction 105 | # Global rule: "Use TypeScript for all code" 106 | # Frontend rule: "React components must have .tsx extension" 107 | 108 | # Test Prompt: 109 | "Create a React component" 110 | 111 | # Expected AI Behavior: 112 | ✅ Uses .tsx extension (domain-specific rule) 113 | ✅ Implements in TypeScript (global rule) 114 | ✅ No conflicting behavior 115 | ✅ Mentions both rules when relevant 116 | ``` 117 | 118 | ## 🛠️ Testing Methodology 119 | 120 | ### **1. Create Test Scenarios** 121 | 122 | #### **Scenario-Based Testing** 123 | ```markdown 124 | ## Test Scenario: Database Rule Compliance 125 | 126 | ### Context 127 | - Project uses Prisma ORM 128 | - Rule: All database queries must use repository pattern 129 | - Rule: Include error handling for all database operations 130 | 131 | ### Test Cases 132 | 133 | #### Test Case 1: Basic CRUD Operation 134 | **Prompt**: "Create a function to fetch user by ID" 135 | **Expected**: Repository pattern, error handling, TypeScript types 136 | 137 | #### Test Case 2: Complex Query 138 | **Prompt**: "Create a function to search users with filters" 139 | **Expected**: Repository pattern, pagination, validation, error handling 140 | 141 | #### Test Case 3: Transaction Handling 142 | **Prompt**: "Create a function to transfer points between users" 143 | **Expected**: Repository pattern, transaction handling, rollback logic 144 | ``` 145 | 146 | ### **2. Systematic Testing Process** 147 | 148 | #### **Testing Workflow** 149 | ```bash 150 | # Step 1: Prepare Test Environment 151 | # - Clean cursor session 152 | # - Load specific rule set 153 | # - Prepare test project context 154 | 155 | # Step 2: Execute Test Scenarios 156 | # - Run standardized prompts 157 | # - Document AI responses 158 | # - Note adherence to rules 159 | 160 | # Step 3: Evaluate Results 161 | # - Compare against expected behavior 162 | # - Identify rule gaps or conflicts 163 | # - Document improvement areas 164 | 165 | # Step 4: Iterate and Improve 166 | # - Update rules based on findings 167 | # - Re-test improved rules 168 | # - Document changes and rationale 169 | ``` 170 | 171 | ### **3. Rule Effectiveness Metrics** 172 | 173 | #### **Quantitative Metrics** 174 | ```markdown 175 | ## Rule Effectiveness Scorecard 176 | 177 | ### Adherence Rate 178 | - Rule followed correctly: X/Y test cases 179 | - Partial adherence: X/Y test cases 180 | - Rule ignored: X/Y test cases 181 | 182 | ### Productivity Impact 183 | - Time saved per development task 184 | - Consistency improvement (subjective 1-10) 185 | - Reduction in code review feedback 186 | 187 | ### Integration Success 188 | - Works with workflow system: ✅/❌ 189 | - Works with epic planning: ✅/❌ 190 | - No conflicts with other rules: ✅/❌ 191 | ``` 192 | 193 | ## 🧪 Testing Tools and Techniques 194 | 195 | ### **1. Rule Test Templates** 196 | 197 | #### **Basic Rule Test Template** 198 | ```markdown 199 | ## Rule Test: [RULE_NAME] 200 | 201 | ### Rule Description 202 | [Brief description of what the rule should accomplish] 203 | 204 | ### Test Environment 205 | - Project type: [frontend/backend/fullstack] 206 | - Technology stack: [specific technologies] 207 | - Other active rules: [list relevant rules] 208 | 209 | ### Test Cases 210 | 211 | #### Test Case 1: [SCENARIO_NAME] 212 | **Prompt**: "[Exact prompt used for testing]" 213 | **Expected Behavior**: 214 | - [ ] Specific behavior 1 215 | - [ ] Specific behavior 2 216 | - [ ] Specific behavior 3 217 | 218 | **Actual Result**: [Document what actually happened] 219 | **Status**: ✅ Pass / ⚠️ Partial / ❌ Fail 220 | **Notes**: [Any observations or improvements needed] 221 | 222 | #### Test Case 2: [SCENARIO_NAME] 223 | [Repeat pattern...] 224 | 225 | ### Overall Assessment 226 | **Rule Effectiveness**: [1-10 score] 227 | **Recommended Actions**: [Improvements needed] 228 | **Test Date**: [Date] 229 | **Tester**: [Name] 230 | ``` 231 | 232 | ### **2. Automated Testing Approaches** 233 | 234 | #### **Rule Validation Script** 235 | ```bash 236 | # Create a simple test runner for rule validation 237 | # This tests if rules are properly formatted and loaded 238 | 239 | # Test script example: 240 | cat > test-rules.sh << 'EOF' 241 | #!/bin/bash 242 | 243 | echo "Testing Cursor Rule Framework rules..." 244 | 245 | # Test 1: Check rule files exist 246 | echo "✅ Checking rule files..." 247 | if [ ! -f ".cursor/rules/project-config.mdc" ]; then 248 | echo "❌ project-config.mdc missing" 249 | exit 1 250 | fi 251 | 252 | # Test 2: Validate YAML frontmatter 253 | echo "✅ Validating YAML frontmatter..." 254 | for file in .cursor/rules/*.mdc; do 255 | if ! head -n 10 "$file" | grep -q "^---$"; then 256 | echo "❌ Invalid frontmatter in $file" 257 | exit 1 258 | fi 259 | done 260 | 261 | # Test 3: Check for required fields 262 | echo "✅ Checking required fields..." 263 | for file in .cursor/rules/*.mdc; do 264 | if ! grep -q "description:" "$file"; then 265 | echo "❌ Missing description in $file" 266 | exit 1 267 | fi 268 | done 269 | 270 | echo "✅ All rule validation tests passed!" 271 | EOF 272 | 273 | chmod +x test-rules.sh 274 | ./test-rules.sh 275 | ``` 276 | 277 | ### **3. Real-World Testing** 278 | 279 | #### **Production Testing Protocol** 280 | ```bash 281 | # Test rules in real development scenarios 282 | 283 | # 1. Use rules for actual feature development 284 | "Implement user authentication using our established patterns" 285 | 286 | # 2. Track AI behavior over multiple interactions 287 | # - Does consistency improve over time? 288 | # - Are patterns correctly reused? 289 | # - Do rules prevent common mistakes? 290 | 291 | # 3. Measure team adoption 292 | # - Do team members report improved AI interactions? 293 | # - Are code reviews finding fewer pattern violations? 294 | # - Is development velocity improving? 295 | ``` 296 | 297 | ## 📊 Testing Examples 298 | 299 | ### **Example 1: Frontend Component Rule Testing** 300 | 301 | #### **Rule Under Test** 302 | ```yaml 303 | --- 304 | description: React component development standards with TypeScript and testing 305 | globs: "src/components/**/*.{tsx,ts}" 306 | alwaysApply: false 307 | --- 308 | 309 | # React Component Standards 310 | - Use functional components with TypeScript 311 | - Include prop interface definitions 312 | - Add unit tests for all components 313 | - Follow naming convention: PascalCase 314 | ``` 315 | 316 | #### **Test Execution** 317 | ```bash 318 | # Test Case: Component Creation 319 | Prompt: "Create a UserCard component that displays user name and email" 320 | 321 | # Expected AI Response Checklist: 322 | ✅ Creates UserCard.tsx (correct naming) 323 | ✅ Uses functional component pattern 324 | ✅ Defines props interface (UserCardProps) 325 | ✅ Includes TypeScript types 326 | ✅ Creates UserCard.test.tsx 327 | ✅ Includes basic rendering test 328 | ✅ Uses proper import/export structure 329 | 330 | # Actual Result Documentation: 331 | ✅ All behaviors observed correctly 332 | ⚠️ AI didn't automatically create test file (needs rule enhancement) 333 | ✅ TypeScript interfaces properly defined 334 | ✅ Naming conventions followed 335 | ``` 336 | 337 | ### **Example 2: API Development Rule Testing** 338 | 339 | #### **Rule Under Test** 340 | ```yaml 341 | --- 342 | description: API endpoint development with error handling and validation 343 | globs: "src/api/**/*.ts" 344 | alwaysApply: true 345 | --- 346 | 347 | # API Development Standards 348 | - Use Express.js patterns 349 | - Include request validation with Zod 350 | - Implement proper error handling 351 | - Return consistent response format 352 | - Include OpenAPI documentation 353 | ``` 354 | 355 | #### **Test Execution** 356 | ```bash 357 | # Test Case: CRUD Endpoint Creation 358 | Prompt: "Create an API endpoint for creating new blog posts" 359 | 360 | # Expected AI Response Checklist: 361 | ✅ Uses Express.js router pattern 362 | ✅ Includes Zod validation schema 363 | ✅ Implements try-catch error handling 364 | ✅ Returns consistent JSON response format 365 | ✅ Includes basic OpenAPI comments 366 | ✅ Follows RESTful conventions (POST /api/posts) 367 | 368 | # Actual Result Documentation: 369 | ✅ Express pattern correctly implemented 370 | ✅ Zod validation included 371 | ❌ Error handling was basic, needs improvement 372 | ✅ Response format consistent 373 | ⚠️ OpenAPI comments minimal (needs rule clarification) 374 | ``` 375 | 376 | ## 🎯 Best Practices for Rule Testing 377 | 378 | ### **1. Test Early and Often** 379 | - Test rules as you create them 380 | - Include testing in rule development workflow 381 | - Regular regression testing for existing rules 382 | 383 | ### **2. Use Real Development Scenarios** 384 | - Test with actual project requirements 385 | - Include edge cases and complex scenarios 386 | - Test rule combinations, not just individual rules 387 | 388 | ### **3. Document Everything** 389 | - Keep test results for rule improvement 390 | - Share findings with team 391 | - Track rule effectiveness over time 392 | 393 | ### **4. Iterate Based on Results** 394 | - Update rules based on test findings 395 | - Remove or modify ineffective rules 396 | - Continuously improve rule clarity and specificity 397 | 398 | ### **5. Team-Based Testing** 399 | - Have multiple team members test the same rules 400 | - Compare results and experiences 401 | - Ensure rules work across different development styles 402 | 403 | ## 🚀 Advanced Testing Techniques 404 | 405 | ### **A/B Testing for Rules** 406 | ```bash 407 | # Compare rule variations to find most effective version 408 | 409 | # Version A: Specific rule 410 | "Use React.useState for component state management" 411 | 412 | # Version B: General rule 413 | "Manage component state appropriately" 414 | 415 | # Test both versions with same prompts 416 | # Measure specificity and consistency of AI responses 417 | # Choose version that produces better results 418 | ``` 419 | 420 | ### **Integration Testing with Workflow** 421 | ```bash 422 | # Test complete workflow with rules 423 | # Blueprint → Construct → Validate cycle 424 | # Ensure rules work at each phase 425 | # Verify epic integration functions correctly 426 | # Test architecture.mdc updates work properly 427 | ``` 428 | 429 | ### **Performance Impact Testing** 430 | ```bash 431 | # Measure rule impact on development velocity 432 | # Time common development tasks with and without rules 433 | # Measure code quality improvements 434 | # Track reduction in debugging time 435 | # Monitor team satisfaction with AI interactions 436 | ``` 437 | 438 | --- 439 | 440 | **Rule testing ensures your Cursor Rule Framework implementation provides consistent, high-quality AI assistance that truly improves development productivity.** -------------------------------------------------------------------------------- /docs/for-developers.md: -------------------------------------------------------------------------------- 1 | # 👨‍💻 For Developers: Individual Workflow Guide 2 | 3 | How to leverage the Cursor Rule Framework for enhanced individual development productivity. 4 | 5 | ## 🎯 Quick Start for Developers 6 | 7 | ### **Day 1: Basic Setup (10 minutes)** 8 | 9 | #### **Setup Steps:** 10 | 1. Install Cursor IDE if not already installed 11 | 2. Copy user rules template to Cursor settings 12 | 3. Clone/setup your project with framework rules 13 | 14 | #### **Quick Verification:** 15 | 16 | **User Request:** 17 | ```bash 18 | "What rules apply to this file?" 19 | ``` 20 | 21 | **Expected AI Response:** 22 | ```bash 23 | "This TypeScript React component file has the following rules active: 24 | - Component Development Standards (naming, structure, accessibility) 25 | - TypeScript Standards (interfaces, type safety) 26 | - Testing Requirements (unit tests, accessibility tests) 27 | - Styling Standards (Tailwind CSS patterns)" 28 | ``` 29 | 30 | ### **Week 1: Learning the Workflow** 31 | 32 | Practice the three-phase workflow on small tasks: 33 | 34 | #### **User Request:** 35 | ```bash 36 | "Enter Blueprint phase: Create a UserProfile component with props for user data and edit callback" 37 | ``` 38 | 39 | #### **AI Response:** 40 | ```bash 41 | "I'll start the Blueprint phase for the UserProfile component. Let me plan the component structure and review our established patterns." 42 | 43 | # AI will: 44 | # ✅ Plan the component structure 45 | # ✅ Review architecture patterns 46 | # ✅ Create detailed implementation plan 47 | # ✅ Set workflow state to BLUEPRINT 48 | ``` 49 | 50 | #### **Continue to Implementation:** 51 | 52 | **User Request:** 53 | ```bash 54 | "Proceed to Construct phase" 55 | ``` 56 | 57 | **AI Response:** 58 | ```bash 59 | "Moving to Construct phase. I'll implement the UserProfile component according to the approved plan." 60 | # AI implements according to plan 61 | ``` 62 | 63 | #### **Final Validation:** 64 | 65 | **User Request:** 66 | ```bash 67 | "Proceed to Validate phase" 68 | ``` 69 | 70 | **AI Response:** 71 | ```bash 72 | "Entering Validate phase. I'll test the component and verify it meets all requirements." 73 | # AI tests and validates the implementation 74 | ``` 75 | 76 | ### **Week 2: Epic Integration** 77 | 78 | Start working with epics for larger features: 79 | 80 | #### **Create New Epic:** 81 | 82 | **User Request:** 83 | ```bash 84 | "Create a new epic for implementing user authentication with JWT" 85 | ``` 86 | 87 | **AI Response:** 88 | ```bash 89 | "I'll create a comprehensive user authentication epic with JWT implementation. Let me structure this into phases covering registration, login, token management, and security features." 90 | ``` 91 | 92 | #### **Work on Epic Steps:** 93 | 94 | **User Request:** 95 | ```bash 96 | "Work on the login component from the user authentication epic" 97 | ``` 98 | 99 | **AI Response:** 100 | ```bash 101 | "I'll start working on the login component from the User Authentication Epic, Phase 1: Core Authentication. Let me begin with the Blueprint phase to plan the implementation." 102 | 103 | # AI will: 104 | # ✅ Reference epic context and requirements 105 | # ✅ Apply relevant rules for authentication 106 | # ✅ Update epic progress automatically 107 | ``` 108 | 109 | ## 💻 Daily Development Workflow 110 | 111 | ### **Starting Your Day** 112 | ```bash 113 | # 1. Check current epic status 114 | "Show me the status of active epics and what I should work on next" 115 | 116 | # 2. Review architecture for context 117 | "Summarize recent architecture changes and how they affect my current work" 118 | 119 | # 3. Plan your development session 120 | "Plan my development session for implementing the user dashboard components" 121 | ``` 122 | 123 | ### **Feature Development Process** 124 | 125 | #### **Small Features (< 2 hours)** 126 | ```bash 127 | # Use simplified workflow for quick features 128 | "Implement a loading spinner component for our design system" 129 | 130 | # AI will: 131 | # ✅ Apply component rules automatically 132 | # ✅ Follow established patterns 133 | # ✅ Create tests if required by rules 134 | # ✅ Update documentation 135 | ``` 136 | 137 | #### **Medium Features (2 hours - 2 days)** 138 | ```bash 139 | # Use full workflow for structured development 140 | "Enter Blueprint phase: Create a user settings page with profile editing and password change" 141 | 142 | # Follow through all phases: 143 | # Blueprint → Plan and get approval 144 | # Construct → Implement according to plan 145 | # Validate → Test and ensure quality 146 | ``` 147 | 148 | #### **Large Features (3+ days)** 149 | ```bash 150 | # Use epic-driven development 151 | "Create an epic for implementing real-time notifications system" 152 | 153 | # Break into phases and steps: 154 | # Epic → Phases → Steps → Workflow items 155 | # Track progress automatically 156 | ``` 157 | 158 | ### **Problem-Solving Workflow** 159 | 160 | #### **Bug Fixes** 161 | ```bash 162 | # Quick fixes (no formal workflow needed) 163 | "Fix the TypeScript error in UserCard component" 164 | 165 | # Complex bugs (use workflow) 166 | "Enter Blueprint phase: Debug and fix the authentication token refresh issue" 167 | ``` 168 | 169 | #### **Code Reviews** 170 | ```bash 171 | # Get rule-aware feedback 172 | "Review this pull request against our established patterns and rules" 173 | 174 | # AI will: 175 | # ✅ Check rule compliance 176 | # ✅ Suggest improvements based on patterns 177 | # ✅ Identify architecture violations 178 | # ✅ Recommend testing improvements 179 | ``` 180 | 181 | #### **Refactoring** 182 | ```bash 183 | # Plan refactoring with architecture awareness 184 | "Enter Blueprint phase: Refactor the user service to use repository pattern" 185 | 186 | # AI will: 187 | # ✅ Review current architecture 188 | # ✅ Plan migration strategy 189 | # ✅ Identify breaking changes 190 | # ✅ Update architecture documentation 191 | ``` 192 | 193 | ## 🛠️ Personal Productivity Tips 194 | 195 | ### **Contextual Development** 196 | ```bash 197 | # Always provide context for better assistance 198 | "Working on the checkout flow epic, implement payment validation" 199 | 200 | # Instead of: 201 | "Implement payment validation" 202 | 203 | # AI uses epic context for: 204 | # ✅ Consistent patterns within the epic 205 | # ✅ Relevant business requirements 206 | # ✅ Architecture decisions for this feature area 207 | ``` 208 | 209 | ### **Rule-Aware Coding** 210 | ```bash 211 | # Ask about applicable rules 212 | "What rules apply to API endpoint development in this project?" 213 | 214 | # Get pattern suggestions 215 | "Show me the standard pattern for creating a new database model" 216 | 217 | # Validate against rules 218 | "Does this component follow our established React patterns?" 219 | ``` 220 | 221 | ### **Architecture-Conscious Development** 222 | ```bash 223 | # Check architectural impact 224 | "How does adding this new service affect our current architecture?" 225 | 226 | # Get guidance for complex decisions 227 | "What's the recommended approach for handling user sessions in our architecture?" 228 | 229 | # Document architectural changes 230 | "This API change affects our authentication flow - update architecture documentation" 231 | ``` 232 | 233 | ### **Epic Progress Management** 234 | ```bash 235 | # Track your contribution to larger initiatives 236 | "Update my progress on the user management epic" 237 | 238 | # See the bigger picture 239 | "Show me how my current work fits into the overall epic goals" 240 | 241 | # Plan next steps 242 | "What should I work on next for the user management epic?" 243 | ``` 244 | 245 | ## 📈 Skill Development 246 | 247 | ### **Learning Project Patterns** 248 | ```bash 249 | # Understand established patterns 250 | "Explain the authentication pattern used in this project" 251 | 252 | # Learn from examples 253 | "Show me examples of how we handle API errors in this codebase" 254 | 255 | # Get pattern variations 256 | "What are different ways to implement state management following our rules?" 257 | ``` 258 | 259 | ### **Best Practice Adoption** 260 | ```bash 261 | # Learn why patterns exist 262 | "Why do our rules require TypeScript interfaces for all React props?" 263 | 264 | # Understand trade-offs 265 | "What are the benefits and drawbacks of our current database access pattern?" 266 | 267 | # See improvements over time 268 | "How have our testing patterns evolved and why?" 269 | ``` 270 | 271 | ### **Knowledge Building** 272 | ```bash 273 | # Build understanding incrementally 274 | "Explain how our API authentication works from the database to the frontend" 275 | 276 | # Connect different parts of the system 277 | "How does the user registration flow connect to our email service?" 278 | 279 | # Learn architectural reasoning 280 | "What architectural decisions led to our current microservice boundaries?" 281 | ``` 282 | 283 | ## 🔧 Customization for Individual Needs 284 | 285 | ### **Personal Productivity Rules** 286 | Create personal rules for your development style: 287 | 288 | ```yaml 289 | --- 290 | description: "Personal development workflow preferences" 291 | alwaysApply: true 292 | priority: 2 293 | --- 294 | 295 | # Personal Development Preferences 296 | 297 | ## Code Review Checklist 298 | Before submitting PRs, ensure: 299 | - [ ] Tests cover new functionality 300 | - [ ] Documentation updated for API changes 301 | - [ ] Performance impact considered 302 | - [ ] Accessibility requirements met 303 | 304 | ## Development Environment 305 | - Use debugging breakpoints over console.log 306 | - Run tests before committing 307 | - Keep commit messages descriptive and atomic 308 | - Sync with main branch daily 309 | ``` 310 | 311 | ### **Technology-Specific Shortcuts** 312 | ```bash 313 | # Create shortcuts for common tasks 314 | "Create a new React component with my standard setup" 315 | # (TypeScript, testing, styling, prop interfaces) 316 | 317 | "Set up a new API endpoint with full validation" 318 | # (Zod schema, error handling, tests, documentation) 319 | 320 | "Initialize a new database model" 321 | # (Prisma schema, migrations, repository pattern) 322 | ``` 323 | 324 | ### **Learning Goals Integration** 325 | ```bash 326 | # Incorporate learning into development 327 | "I'm learning about React performance - show me opportunities to optimize this component" 328 | 329 | "I want to practice TypeScript advanced types - suggest improvements to this interface" 330 | 331 | "Help me understand GraphQL by converting this REST endpoint" 332 | ``` 333 | 334 | ## 🎯 Measuring Your Progress 335 | 336 | ### **Daily Metrics** 337 | Track your improvement with the framework: 338 | 339 | ```markdown 340 | ## Daily Development Log 341 | 342 | ### Efficiency Gains 343 | - Time saved by rule automation: ~30 minutes/day 344 | - Consistent patterns without lookup: 15+ instances 345 | - Automatic architecture updates: 5 components documented 346 | 347 | ### Quality Improvements 348 | - Rule compliance: 95% (up from 60% without framework) 349 | - Code review feedback: 2 items (down from 8 average) 350 | - Test coverage: 90% (automatic with component rules) 351 | 352 | ### Learning Progress 353 | - New patterns learned: Repository pattern, Factory pattern 354 | - Architecture understanding: Microservice boundaries, Event sourcing 355 | - Technology skills: Advanced TypeScript, React performance 356 | ``` 357 | 358 | ### **Weekly Reviews** 359 | ```bash 360 | # Review your epic contributions 361 | "Show me my contributions to active epics this week" 362 | 363 | # Assess rule effectiveness 364 | "Which rules helped me most this week and which could be improved?" 365 | 366 | # Plan learning goals 367 | "Based on my recent work, what should I focus on learning next week?" 368 | ``` 369 | 370 | ### **Monthly Assessments** 371 | ```bash 372 | # Track long-term growth 373 | "How has my code quality improved since adopting the framework?" 374 | 375 | # Evaluate workflow effectiveness 376 | "What parts of the development workflow are working well and what needs adjustment?" 377 | 378 | # Set development goals 379 | "Based on current project needs, what skills should I develop next month?" 380 | ``` 381 | 382 | ## 🚀 Advanced Individual Techniques 383 | 384 | ### **Multi-Project Pattern Reuse** 385 | ```bash 386 | # Apply patterns across projects 387 | "Apply the authentication pattern from Project A to this new project" 388 | 389 | # Transfer architectural knowledge 390 | "How would the microservice pattern from my previous project work here?" 391 | 392 | # Reuse successful rules 393 | "Adapt the testing patterns from my React project to this Vue.js project" 394 | ``` 395 | 396 | ### **Personal Innovation** 397 | ```bash 398 | # Experiment with new patterns 399 | "Let's try implementing this component with a different state management approach" 400 | 401 | # Test rule variations 402 | "What if we modified our API error handling pattern to include retry logic?" 403 | 404 | # Contribute improvements 405 | "I found a better way to handle form validation - let's update the rule" 406 | ``` 407 | 408 | ### **Framework Contribution** 409 | ```bash 410 | # Identify improvement opportunities 411 | "This rule could be more specific - here's what I learned from using it" 412 | 413 | # Share effective patterns 414 | "This new pattern worked well for user onboarding - should we add it as a rule?" 415 | 416 | # Help team adoption 417 | "I found a good way to explain epic planning to new team members" 418 | ``` 419 | 420 | ## 💡 Tips for Success 421 | 422 | ### **Consistency is Key** 423 | - Use the framework for all significant development work 424 | - Don't skip workflow phases for "quick" features 425 | - Trust the process even when it feels slower initially 426 | - Maintain epic context for related work 427 | 428 | ### **Active Learning** 429 | - Ask "why" about patterns and rules 430 | - Experiment with variations in non-critical code 431 | - Study the architecture documentation regularly 432 | - Connect daily work to larger system understanding 433 | 434 | ### **Continuous Improvement** 435 | - Track what works and what doesn't 436 | - Suggest rule improvements based on real usage 437 | - Share learnings with team members 438 | - Adapt the framework to your development style 439 | 440 | ### **Balance Structure and Flexibility** 441 | - Use full workflow for complex features 442 | - Apply rules consistently but adapt when needed 443 | - Maintain epic context but don't over-organize 444 | - Document patterns but don't over-document 445 | 446 | --- 447 | 448 | **The Cursor Rule Framework transforms individual development from ad-hoc coding to structured, architecture-aware, and continuously improving software engineering practice.** --------------------------------------------------------------------------------