MCP Agile Flow

This file is a merged representation of a subset of the codebase, containing files not matching ignore patterns, combined into a single document by Repomix. The content has been processed where content has been compressed (code blocks are separated by ⋮---- delimiter). <file_summary> This section contains a summary of this file. <purpose> This file contains a packed representation of the entire repository's contents. It is designed to be easily consumable by AI systems for analysis, code review, or other automated processes. </purpose> <file_format> The content is organized as follows: 1. This summary section 2. Repository information 3. Directory structure 4. Repository files, each consisting of: - File path as an attribute - Full contents of the file </file_format> <usage_guidelines> - This file should be treated as read-only. Any changes should be made to the original repository files, not this packed version. - When processing this file, use the file path to distinguish between different files in the repository. - Be aware that this file may contain sensitive information. Handle it with the same level of security as you would the original repository. </usage_guidelines> <notes> - Some files may have been excluded based on .gitignore rules and Repomix's configuration - Binary files are not included in this packed representation. Please refer to the Repository Structure section for a complete list of file paths, including binary files - Files matching these patterns are excluded: xnotes/, node_modules/, build/, temp/, .DS_Store, .gitignore - Files matching patterns in .gitignore are excluded - Files matching default ignore patterns are excluded - Content has been compressed - code blocks are separated by ⋮---- delimiter </notes> <additional_info> </additional_info> </file_summary> <directory_structure> .cursor/ rules/ 000-cursor-rules.mdc 001-emoji-communication.mdc 400-md-docs.mdc templates/ template-arch.md template-prd.md template-story.md docs/ agile-readme.md .cursorignore .cursorindexingignore apply-rules.bat apply-rules.sh readme.md </directory_structure> <files> This section contains the contents of the repository's files. <file path=".cursor/rules/000-cursor-rules.mdc"> --- description: Use ALWAYS when asked to CREATE A RULE or UPDATE A RULE or taught a lesson from the user that should be retained as a new rule for Cursor globs: .cursor/rules/*.mdc alwaysApply: false --- # Cursor Rules Format ## Template Structure for Rules Files ```mdc --- description: ACTION when TRIGGER to OUTCOME globs: .cursor/rules/**/*.mdc alwaysApply: {true or false} --- # Rule Title ## Context - When to apply this rule - Prerequisites or conditions ## Requirements - Concise, actionable items - Each requirement must be testable ## Examples <example> Good concise example with explanation </example> <example type="invalid"> Invalid concise example with explanation </example> ## Critical Rules - Always do X - NEVER do Y ``` ## File Organization ### Location - Path: `.cursor/rules/` - Extension: `.mdc` ### Naming Convention PREFIX-name.mdc where PREFIX is: - 0XX: Core standards - 1XX: Tool configs - 3XX: Testing standards - 1XXX: Language rules - 2XXX: Framework rules - 8XX: Workflows - 9XX: Templates - _name.mdc: Private rules ### Glob Pattern Examples Common glob patterns for different rule types: - Core standards: .cursor/rules/*.mdc - Language rules: src/**/*.{js,ts} - Testing standards: **/*.test.{js,ts} - React components: src/components/**/*.tsx - Documentation: docs/**/*.md - Configuration files: *.config.{js,json} - Build artifacts: dist/**/* - Multiple extensions: src/**/*.{js,jsx,ts,tsx} - Multiple files: dist/**/*, docs/**/*.md ## Required Fields ### Frontmatter - description: ACTION TRIGGER OUTCOME format - globs: `glob pattern for files and folders` - alwaysApply: {true or false} - when true will be attached to every conversation (but front matter still is important for it to be used!) ### Body - context: Usage conditions - requirements: Actionable items - examples: Both valid and invalid - critical-rules: summary of short rule bullets that are the most critical to abide by ## Formatting Guidelines - Use Concise Markdown primarily - Use some XML tags limited to: - <example> - <danger> - <required> - Always indent content within XML or nested XML tags by 2 spaces - Emojies and Mermaid diagrams are allowed if it is not redundant and better explains the rule for the AI comprehension. ## Critical Rules - Keep frontmatter description under 120 characters (or less) while maintaining clear intent for rule selection by AI Agent - Keep the rule DRY - do not repeate or be redundant or overly explanetory. - Use susinct markdown the agent can easily understand. - the front matter MUST ALWAYS have description, globs, and alwaysApply, even if the value is null - Use standard glob patterns without quotes (e.g., *.js, src/**/*.ts) - TRY to keep the total rule line count under 50, better under 25, lines (unless there are diagrams or longer required examples, as that will increase the overall line count) - Always include a valid and invalid example - Quotes are not needed around glob patterns </file> <file path=".cursor/rules/001-emoji-communication.mdc"> --- description: Use emojis strategically in AI responses to enhance communication and user experience globs: null alwaysApply: true --- # Emoji Communication Guidelines ## Context - When responding to user queries in conversations - When emphasizing important points or status updates - When making technical communication more engaging and human-friendly ## Requirements - Use emojis purposefully to enhance meaning, but feel free to be creative and fun - Place emojis at the end of statements or sections - Maintain professional tone while surprising users with clever choices - Limit emoji usage to 1-2 per major section ## Examples <example> ✅ "I've optimized your database queries 🏃‍♂️💨" ✅ "Your bug has been squashed 🥾🐛" ✅ "I've cleaned up the legacy code 🧹✨" ✅ "Fixed the performance issue 🐌➡️🐆" </example> <example type="invalid"> ❌ "Multiple 🎉 emojis 🎊 in 🌟 one message" ❌ "Using irrelevant emojis 🥑" ❌ "Placing the emoji in the middle ⭐️ of a sentence" </example> ## Critical Rules - Never use more than one emoji per statement - Choose emojis that are both fun and contextually appropriate - Place emojis at the end of statements, not at the beginning or middle - Skip emoji usage when discussing serious issues or errors - Don't be afraid to tell a mini-story with your emoji choice </file> <file path=".cursor/rules/400-md-docs.mdc"> --- description: ALWAYS use when writing or updating Markdown files to ensure consistent formatting and readability globs: **/*.md alwaysApply: false --- # Markdown Documentation Standards ## Context - When creating or modifying any Markdown documentation - When establishing documentation structure and style - When including diagrams, code blocks, or special elements in documentation ## Requirements - Follow the official Markdown Guide for all basic and extended syntax - Maintain clear document structure with proper heading hierarchy - Include appropriate YAML front matter for metadata when required - Use Mermaid diagrams for visual documentation where appropriate - Properly format code blocks, tables, and special elements - Maximum heading depth: 4 levels - Indent content within XML tags by 2 spaces - Keep tables simple and readable with proper alignment ## Examples <example> # Document Title ## Section Heading Content with **bold text** and *italics*. ```typescript function example(): void { console.log('Hello, Universe!'); } ``` | Name | Type | Description | |:------|:------:|-------------:| | id | number | Primary key | | name | string | User's name | > 💡 **Tip:** Helpful suggestion. </example> <example type="invalid"> #Incorrect Heading content without proper spacing ``` function withoutLanguageSpecified() { } ``` | No | alignment | markers | | or | proper | formatting | </example> ## Critical Rules - Use ATX-style headings with space after hash: `# Heading` - Maintain proper heading hierarchy (don't skip levels) - Add blank line before and after headings and blocks - Specify language in code blocks using triple backticks - Use blockquotes with emoji for different types of callouts - Include clear titles for Mermaid diagrams using the `---` syntax - Keep table structure clean with proper alignment indicators - Format Mermaid diagrams with descriptive node labels and comments - Close XML tags on their own line at the parent indentation level </file> <file path=".cursor/templates/template-arch.md"> # Architecture Template <version>1.0.0</version> ## Requirements - Document architectural decisions clearly - Maintain a Changelog - Judicious use of mermaid diagrams ## Structure ### Required Sections #### 1. Title {Architecture for {project}} #### 2. Status - Draft - Approved #### 3. Technical Summary #### 4. Technology Table Table listing choices for languages, libraries, infra, etc... - column for technology - column for descrpition #### 5. Arhictectural Diagrams - Mermaid Diagrams as needed #### 6. Data Models, API Specs, Schemas, etc... - not exhaustive - but key ideas that need to be retained and followed across stories #### 7. Project Structure document the folder and file organization and structure along with descriptions #### 8. Change Log markdown table of key changes after document is no longer in draft and is updated, table includes the change title, the story id that the change happened during, and a description if the title is not clear enough ## Examples <example> # Architecture for Sensor Data Processing Platform ## Status: Approved ## Technical Summary This architecture defines a scalable, fault-tolerant platform for processing real-time sensor data from multiple sources. The system employs a microservices architecture to ensure high availability, scalability, and maintainability while supporting real-time data processing and analysis. ## Technology Table | Technology | Description | | ------------ | ------------------------------------------------------------- | | Kubernetes | Container orchestration platform for microservices deployment | | Apache Kafka | Event streaming platform for real-time data ingestion | | TimescaleDB | Time-series database for sensor data storage | | Go | Primary language for data processing services | | GoRilla Mux | REST API Framework | | Python | Used for data analysis and ML services | | gRPC | Inter-service communication protocol | | Prometheus | Metrics collection and monitoring | | Grafana | Visualization and dashboarding | ## Architectural Diagrams ```mermaid graph TD A[Sensor Gateway] -->|Raw Data| B[Kafka] B --> C[Data Processor] B --> D[Alert Service] C --> E[(TimescaleDB)] C --> F[Analytics Engine] D --> G[Notification Service] F --> H[ML Predictor] style A fill:#f9f,stroke:#333 style B fill:#bbf,stroke:#333 style C fill:#bfb,stroke:#333 ``` ```mermaid sequenceDiagram participant S as Sensor participant G as Gateway participant K as Kafka participant P as Processor participant DB as TimescaleDB S->>G: Send Data G->>K: Publish Event K->>P: Consume Event P->>DB: Store Processed Data ``` ## Data Models ### Sensor Reading Schema ```json { "sensor_id": "string", "timestamp": "datetime", "readings": { "temperature": "float", "pressure": "float", "humidity": "float" }, "metadata": { "location": "string", "calibration_date": "datetime" } } ``` ## Project Structure ``` / ├── /services │ ├── /gateway # Sensor data ingestion │ ├── /processor # Data processing and validation │ ├── /analytics # Data analysis and ML │ └── /notifier # Alert and notification system ├── /deploy │ ├── /kubernetes # K8s manifests │ └── /terraform # Infrastructure as Code └── /docs ├── /api # API documentation └── /schemas # Data schemas ``` ## Change Log | Change | Story ID | Description | | -------------------- | -------- | ------------------------------------------------------------- | | Initial Architecture | N/A | Initial approved system design and documentation | | Add ML Pipeline | story-4 | Integration of machine learning prediction service | | Kafka Upgrade | story-6 | Upgraded from Kafka 2.0 to Kafka 3.0 for improved performance | </example> <example type="invalid"> # Simple Architecture Just use a database and some APIs. Maybe add caching later if needed. Tech stack: - Whatever is easiest - Probably MongoDB - Some framework No diagrams or proper documentation included. </example> </file> <file path=".cursor/templates/template-prd.md"> # PRD Template Standards <version>1.0.0</version> ## Requirements - Follow standardized PRD structure - Include all required sections - Maintain proper documentation hierarchy - Use consistent formatting ## PRD Structure ### Required Sections #### 1. Header - Title: "Product Requirements Document (PRD) for {project-name}" #### 2. Status - Draft - Approved #### 3. Introduction - Clear description of {project-name} - Overview of the project scope - Business context and drivers - Target users/stakeholders #### 4. Goals - Clear project objectives - Measurable outcomes - Success criteria - Key performance indicators (KPIs) #### 5. Features and Requirements - Functional requirements - Non-functional requirements - User experience requirements - Integration requirements - Compliance requirements #### 6. Epic Structure - At least one Epic must be defined - Format: Epic-{N}: {Title} ({Status}) - Status can be: Current, Future, Complete - Only one Epic can be "Current" at a time - Each Epic represents a major feature or functionality - Epics must be implemented sequentially #### 7. Story List - Stories are organized under Epics - Format: Story-{N}: {Description of story/task} <note>The details of the story will be drafted later in story files</note> #### 8. Tech Stack - languages - frameworks - note: this will be further defined in more detail in the arch document> #### 9. Future Enhancements - Potential Epics for future consideration - Ideas collected during Epic progression - Prioritization guidelines - Impact assessment ## Examples <example type="valid"> # Product Requirements Document (PRD) for Imperial Defense Platform v2 ## Status: Draft ## Introduction The Imperial Defense Platform v2 (IDP2) is a state-of-the-art battle station designed to maintain peace and order throughout the galaxy. This project encompasses the development of a fully operational space station with unprecedented defensive capabilities. The platform will serve as both a military installation and a symbol of Imperial might. ## Goals - Achieve 200% increase in planetary defense coverage compared to v1 - Reduce response time to rebel incursions by 75% - Implement automated defense systems with 99.99% accuracy - Establish capacity for housing 1.2 million Imperial personnel - Achieve energy self-sufficiency through advanced reactor technology ## Features and Requirements ### Functional Requirements - Automated defense grid with predictive targeting - Quantum-encrypted communication systems - Advanced life support systems for 1.2M personnel - Modular construction system for rapid repairs - AI-powered threat detection and response ### Non-functional Requirements - 99.999% system uptime - Sub-millisecond weapon response time - Zero-latency internal communications - Radiation shielding for all habitable areas - Energy efficiency rating of 95% ## Epic Structure Epic-1: Core Infrastructure Development (Complete) Epic-2: Defense Systems Integration (Current) Epic-3: Life Support and Personnel Systems (Future) Epic-4: Command and Control Implementation (Future) ## Story List ### Epic-2: Defense Systems Integration Story-1: Implement primary weapon targeting system Story-2: Develop shield generator network Story-3: Create automated defense grid control interface Story-4: Integration of threat detection AI Story-5: Deploy backup power distribution for weapons ## Tech Stack - Languages: Galactic Basic C++23, QuantumScript - Frameworks: ImperialCore, DefenseGrid Pro - Infrastructure: HyperScale Cloud, QuantumNet - Security: Imperial Grade Encryption (IGE) v4 ## Future Enhancements - Planet-scale tractor beam capability - Advanced cloaking technology integration - Expanded hangar facilities for TIE defender squadrons - Redundant shield generator systems - Deep space hyperspace tracking system </example> <example type="invalid"> Chess Game - Add basic game - Maybe add AI later - Other features we might need </example> </file> <file path=".cursor/templates/template-story.md"> # Story Template <version>1.0.0</version> ## Requirements - Follow standardized story structure - Include all required sections - some will be empty to start with ## Story Structure ### Required Sections #### 1. Header Epic-{N}: {Epic Title} Story-{M}: {Story Title} #### 2. Story Description **As a** {role} **I want** {action} **so that** {benefit} #### 3. Status - Draft - In Progress - Complete - Cancelled #### 4. Context - Background information - Current state - Story justification - Technical context - Business drivers - Relevant history from previous stories #### 5. Estimation Story Points: {Story Points (1 SP = 1 day of Human Development = 10 minutes of AI development)} #### 6. Tasks ##### Task Groups 1. - [ ] {Major Task Group 1} 1. - [ ] {Test Subtasks (as needed)} 2. - [ ] {Subtask} Note: - Use - [x] for completed items - Use ~~skipped/cancelled items~~ - Follow TDD - Start with Writing Tests Subtask ### 7. Additional Sections #### Constraints - List any technical or business constraints #### Data Models / Schema - Database schemas - API request/response models - Interfaces/types #### Structure - Module organization - File structure plan #### Diagrams - Mermaid diagrams as needed #### Dev Notes - Implementation commentary - Important considerations - Technical decisions #### Chat Command Log - Commands from User - Agent Question and Users Response ## Examples <example> # Epic-1: Basic Chess Game # Story-2: Implement Chessboard UI ## Story **As a** chess player **I want** to see a clear and interactive chessboard **so that** I can play chess in the web browser ## Status In Progress ## Context Part of Epic-1 which implements the core 2-player chess game. This story focuses on the visual and interactive aspects of the chessboard. The project setup (Story-1) is complete, providing the foundation for UI implementation. ## Estimation Story Points: 2 ## Tasks 1. - [x] Create Chessboard Grid 1. - [x] Implement 8x8 board layout 2. - [x] Add square coloring 3. - [x] Write grid tests 2. - [ ] Add Chess Pieces 1. - [ ] Create piece components 2. - [ ] Add piece images 3. - [ ] Write piece tests 3. - [ ] Implement Basic Interaction 1. - [ ] Add click handlers 2. - [ ] Highlight selected square 3. - [ ] Write interaction tests ## Dev Notes - Using React for UI components - Chess piece SVGs from open-source library - Implementing responsive design for various screen sizes ## Chat Command Log - BMad: Let's implement the chessboard UI - AiAgent: Reviewing the design requirements. Should we use SVG or PNG for pieces? - BMad: Let's use SVG for better scaling - AiAgent: Grid implementation complete, proceeding with piece placement </example> <example type="invalid"> Chess UI Story todo: - make board - add pieces - make it work </example> </file> <file path="docs/agile-readme.md"> # Cursor Agile Workflow Documentation This document provides comprehensive documentation for the Agile workflow system integrated with Cursor's AI capabilities. The workflow is designed to maintain project focus and ensure consistent progress through a structured approach to development. ## Overview The Agile-Cursor workflow combines traditional Agile methodologies with AI-assisted development to create a powerful, efficient development process. It can be utilized in two primary ways: 1. **Rule-Based Implementation** (Automatic) - Uses `.cursor/rules/` templates - Automatically applies standards to matching files - Provides consistent structure enforcement 2. **Notepad-Based Implementation** (Flexible) - Uses `xnotes/` templates - Lighter weight and more adaptable - Ideal for focused development sessions ## Work Item Hierarchy ```mermaid graph TD E[Epic] --> S[Story] S --> T[Task] T --> ST[Subtask] style E fill:#f9f,stroke:#333,stroke-width:2px style S fill:#dfd,stroke:#333,stroke-width:2px style T fill:#bbf,stroke:#333,stroke-width:2px style ST fill:#ffd,stroke:#333,stroke-width:2px ``` 1. **Epics** - Large, self-contained features - Only one active at a time - Example: "Online Matchmaking System" 2. **Stories** - Smaller, implementable work units - Must belong to an Epic - Example: "User Profile Creation" 3. **Tasks** - Technical implementation steps - Clear completion criteria - Example: "Implement Database Schema" 4. **Subtasks** - Granular work items - Often includes test requirements - Example: "Write Unit Tests" ## AI Project Plan and Memory Structure the Workflow will result in ``` .ai/ ├── prd.md # Product Requirements Document ├── arch.md # Architecture Decision Record ├── epic-1/ # Current Epic directory │ ├── story-1.story.md # Story files for Epic 1 │ ├── story-2.story.md │ └── story-3.story.md ├── epic-2/ # Future Epic directory │ └── ... └── epic-3/ # Future Epic directory └── ... ``` ## Workflow Phases ### 1. PLAN Phase - Focus on documentation and planning - Only modify `.ai/`, docs, readme, and rules - Required approvals for PRD and Architecture ### 2. ACT Phase - Implementation of approved in progress story - Task-by-task execution - Continuous testing and validation ```mermaid graph LR subgraph PLAN Phase A[Project Idea] --> B[PRD Creation] B --> C[Architecture Design] C --> D[Epic Planning] D --> E[Story Definition] end subgraph ACT Phase E --> F[Story Implementation] F --> G[Testing & Validation] G --> H[Story Completion] end subgraph Iteration H --> |Next Story|E H --> |Epic Complete|I[Epic Completion] I --> |Next Epic|D I --> |Project Complete|J[Release] end style A fill:#f9f,stroke:#333,stroke-width:2px style B fill:#dfd,stroke:#333,stroke-width:2px style C fill:#dfd,stroke:#333,stroke-width:2px style D fill:#f9f,stroke:#333,stroke-width:2px style E fill:#bbf,stroke:#333,stroke-width:2px style F fill:#bbf,stroke:#333,stroke-width:2px style G fill:#bbf,stroke:#333,stroke-width:2px style H fill:#bbf,stroke:#333,stroke-width:2px style I fill:#f9f,stroke:#333,stroke-width:2px style J fill:#f9f,stroke:#333,stroke-width:2px ``` ## Implementation Guidelines ### Story Implementation Process 1. **Initialization** - Verify `.ai` directory exists - Locate approved architecture and current story - Ensure story is properly marked as in-progress 2. **Development Flow** - Follow Test-Driven Development (TDD) - Update task/subtask status regularly - Document all implementation notes - Record significant commands used 3. **Completion Requirements** - All tests must pass - Documentation must be updated - User must approve completion ### Critical Rules > 🚨 **Critical Rules:** > > - Never creates first story without PRD and Architecture approval > - Only one Epic can be in-progress at a time > - Only one Story can be in-progress at a time > - Stories must be implemented in PRD-specified order > - Never implement without story approval from user (marked as in progress on the story file) ## Using the Workflow ### Rule-Based Approach 1. Install the workflow rules: ```bash ./apply-rules.sh /path/to/your/project ``` 2. Use the provided templates by copying them into the `.cursor/rules` directory: - `901-prd.mdc` for Product Requirements - `902-arch.mdc` for Architecture - `903-story.mdc` for Stories ### Notepad-Based Approach 1. Enable Notepads in Cursor options 2. Create notepads from templates: - `workflow-agile.md` for full workflow - `implementation-agile.md` for story implementation 3. Use `@notepad-name` to access workflow context > 💡 **Tip:** Use the Notepad approach for: > > - Initial project setup (notepad named plan-agile) > - Story implementation (notepad named impl-story) > - Focused development sessions > - Reducing context overhead - New Context Window Sample Command: `@plan-agile I have an idea for <describe high level here>` - New Context Window Sample Command: `@impl-story I am ready to start implementing the story current in progress story in complete tasks` ## Best Practices 1. **Documentation** - AI will keep PRD and Architecture documents updated - sometimes you will need to tell it to update the prd and arch files as needed. - Document all significant decisions - Maintain clear implementation notes 2. **Testing** - Write tests before implementation - Maintain high test coverage - Verify all tests pass before completion 3. **Progress Tracking** - Update story status regularly - Record all implementation notes - Document command history 4. **Context Management** - Start fresh composer instance per story or after significant recorded progress (recorded in task completion updates) - Use appropriate context level - Minimize context overhead ## Status Progression Stories follow a strict status progression: ``` Draft -> In Progress -> Complete ``` Epics follow a similar progression: ``` Future -> Current -> Complete ``` ## Integration with Cursor AI The workflow is designed to work seamlessly with Cursor's AI capabilities: 1. **AI-Assisted Planning** - AI helps create and refine PRD - AI suggests architecture improvements - AI assists in story breakdown 2. **AI-Assisted Implementation** - AI implements story tasks - AI maintains test coverage - AI updates documentation 3. **AI-Assisted Review** - AI verifies completion criteria - AI suggests improvements - AI maintains consistency ## Cost Savings - LLMs outside of cursory if you have them available, such as ChatGPT, Claude, Gemini, etc are also great to generate the initial PRD and architecture, and really itterate on them. - Within Cursor, currently you can use DeepSeek R1 for example which seems to be free and also decent and udpating PRD and architecture - but I have found it to be a bit less reliable than using Claude to follow the format I want - but much cheaper, if trying to do it all in cursor planning. </file> <file path=".cursorignore"> /node_modules /build /temp .DS_STORE .gitignore /xnotes </file> <file path=".cursorindexingignore"> /xnotes .cursor/templates/*.md </file> <file path="apply-rules.bat"> @echo off setlocal EnableDelayedExpansion chcp 65001 >nul echo DEBUG: Script started REM Vérifier que le répertoire cible est fourni if "%~1"=="" ( echo Error: Please provide the target project directory echo Usage: %~nx0 ^<target-project-directory^> exit /b 1 ) set "TARGET_DIR=%~1" REM Créer le répertoire cible s'il n'existe pas, et initialiser le README.md if not exist "%TARGET_DIR%\" ( echo Creating new project directory: %TARGET_DIR% mkdir "%TARGET_DIR%" ( echo # New Project echo. echo This project has been initialized with agile workflow support and auto rule generation configured from [cursor-auto-rules-agile-workflow](https://github.com/bmadcode/cursor-auto-rules-agile-workflow) echo. echo For workflow documentation, see [Workflow Rules](docs/workflow-rules.md) ) > "%TARGET_DIR%\README.md" ) REM Créer le dossier .cursor\rules if not exist "%TARGET_DIR%\.cursor\rules\" ( mkdir "%TARGET_DIR%\.cursor\rules" ) REM Créer le dossier .cursor\templates if not exist "%TARGET_DIR%\.cursor\templates\" ( mkdir "%TARGET_DIR%\.cursor\templates" ) REM Copier les fichiers de règles de base (sans écraser les existants) echo Copying core rule files... for %%F in (.cursor\rules\*.mdc) do ( if not exist "%TARGET_DIR%\.cursor\rules\%%~nxF" ( copy "%%F" "%TARGET_DIR%\.cursor\rules\" >nul ) ) REM Copier les fichiers templates echo Copying template files... xcopy ".cursor\templates\*.*" "%TARGET_DIR%\.cursor\templates\" /E /I /Y >nul REM Créer le dossier docs et générer le fichier de documentation workflow-rules.md if not exist "%TARGET_DIR%\docs\" ( mkdir "%TARGET_DIR%\docs" ) ( echo # Cursor Workflow Rules echo. echo This project has been updated to use the auto rule generator from [cursor-auto-rules-agile-workflow](https://github.com/bmadcode/cursor-auto-rules-agile-workflow) echo. echo ^> **Note**: This script can be safely re-run at any time to update the template rules to their latest versions^. It will not impact or overwrite any custom rules you've created^. echo. echo ## Core Features echo. echo - Automated rule generation echo - Standardized documentation formats echo - AI behavior control and optimization echo - Flexible workflow integration options echo. echo ## Workflow Integration Options echo. echo ### 1^. Automatic Rule Application (Recommended) echo The core workflow rules are automatically installed in ^.cursor/rules/: echo - `901-prd^.mdc` - Product Requirements Document standards echo - `902-arch^.mdc` - Architecture documentation standards echo - `903-story^.mdc` - User story standards echo - `801-workflow-agile^.mdc` - Complete Agile workflow (optional) echo. echo These rules are automatically applied when working with corresponding file types^. echo. echo ### 2^. Notepad-Based Workflow echo For a more flexible approach, use the templates in `xnotes/`: echo 1^. Enable Notepads in Cursor options echo 2^. Create a new notepad (e^.g^., "agile") echo 3^. Copy contents from `xnotes/workflow-agile^.md` echo 4^. Use `@notepad-name` in conversations echo. echo ^> **Tip:** The Notepad approach is ideal for: echo ^> - Initial project setup echo ^> - Story implementation echo ^> - Focused development sessions echo ^> - Reducing context overhead echo. echo ## Getting Started echo. echo 1^. Review the templates in `xnotes/` echo 2^. Choose your preferred workflow approach echo 3^. Start using the AI with confidence! echo. echo For demos and tutorials, visit: [BMad Code Videos](https://youtube^.com/bmadcode) ) > "%TARGET_DIR%\docs\workflow-rules.md" REM Mettre à jour le .gitignore avec xnotes et docs if exist "%TARGET_DIR%\.gitignore" ( findstr /L /C:".cursor/rules/_*.mdc" "%TARGET_DIR%\.gitignore" >nul if errorlevel 1 ( ( echo. echo # Private individual user cursor rules echo .cursor/rules/_*.mdc echo. echo # Documentation and templates echo xnotes/ echo docs/ ) >> "%TARGET_DIR%\.gitignore" ) ) else ( ( echo # Private individual user cursor rules echo .cursor/rules/_*.mdc echo. echo # Documentation and templates echo xnotes/ echo docs/ ) > "%TARGET_DIR%\.gitignore" ) REM Installer les templates de Notepad echo Setting up Notepad templates... if not exist "%TARGET_DIR%\xnotes\" ( mkdir "%TARGET_DIR%\xnotes" ) xcopy "xnotes\*.*" "%TARGET_DIR%\xnotes\" /E /I /Y >nul REM Mettre à jour le .cursorignore if exist "%TARGET_DIR%\.cursorignore" ( findstr /L /C:"xnotes/" "%TARGET_DIR%\.cursorignore" >nul if errorlevel 1 ( ( echo. echo # Project notes and templates echo xnotes/ ) >> "%TARGET_DIR%\.cursorignore" ) ) else ( ( echo # Project notes and templates echo xnotes/ ) > "%TARGET_DIR%\.cursorignore" ) REM Créer ou mettre à jour le .cursorindexingignore if exist "%TARGET_DIR%\.cursorindexingignore" ( findstr /L /C:".cursor/templates/" "%TARGET_DIR%\.cursorindexingignore" >nul if errorlevel 1 ( ( echo. echo # Templates - accessible but not indexed echo .cursor/templates/ ) >> "%TARGET_DIR%\.cursorindexingignore" ) ) else ( ( echo # Templates - accessible but not indexed echo .cursor/templates/ ) > "%TARGET_DIR%\.cursorindexingignore" ) REM Supprimer le fichier test.txt s'il existe if exist "%TARGET_DIR%\test.txt" ( del "%TARGET_DIR%\test.txt" ) echo. echo Deployment Complete! echo Core rules: %TARGET_DIR%\.cursor\rules\ echo Templates: %TARGET_DIR%\.cursor\templates\ echo Notepad templates: %TARGET_DIR%\xnotes\ echo Documentation: %TARGET_DIR%\docs\workflow-rules.md echo Updated .gitignore, .cursorignore, and .cursorindexingignore echo. echo Next steps: echo 1^. Review the documentation in docs\workflow-rules^.md echo 2^. Choose your preferred workflow approach echo 3^. Enable Cursor Notepads if using the flexible workflow option echo 4^. To start a new project, use xnotes\project-idea-prompt^.md as a template echo to craft your initial message to the AI agent endlocal </file> <file path="apply-rules.sh"> #!/bin/bash # Check if target directory is provided if [ $# -eq 0 ]; then echo "Error: Please provide the target project directory" echo "Usage: ./apply-rules.sh <target-project-directory>" exit 1 fi TARGET_DIR="$1" # Create target directory if it doesn't exist if [ ! -d "$TARGET_DIR" ]; then echo "📁 Creating new project directory: $TARGET_DIR" mkdir -p "$TARGET_DIR" # Initialize readme for new project cat > "$TARGET_DIR/README.md" << 'EOL' # New Project This project has been initialized with agile workflow support and auto rule generation configured from [cursor-auto-rules-agile-workflow](https://github.com/bmadcode/cursor-auto-rules-agile-workflow). For workflow documentation, see [Workflow Rules](docs/workflow-rules.md). EOL fi # Create .cursor/rules directory if it doesn't exist mkdir -p "$TARGET_DIR/.cursor/rules" # Create .cursor/templates directory if it doesn't exist mkdir -p "$TARGET_DIR/.cursor/templates" # Copy core rule files echo "📦 Copying core rule files..." cp -n .cursor/rules/*.mdc "$TARGET_DIR/.cursor/rules/" # Copy template files echo "📦 Copying template files..." cp -r .cursor/templates/* "$TARGET_DIR/.cursor/templates/" # Create docs directory if it doesn't exist mkdir -p "$TARGET_DIR/docs" # Create workflow documentation cat > "$TARGET_DIR/docs/workflow-rules.md" << 'EOL' # Cursor Workflow Rules This project has been updated to use the auto rule generator from [cursor-auto-rules-agile-workflow](https://github.com/bmadcode/cursor-auto-rules-agile-workflow). > **Note**: This script can be safely re-run at any time to update the template rules to their latest versions. It will not impact or overwrite any custom rules you've created. ## Core Features - Automated rule generation - Standardized documentation formats - AI behavior control and optimization - Flexible workflow integration options ## Workflow Integration Options ### 1. Automatic Rule Application (Recommended) The core workflow rules are automatically installed in `.cursor/rules/`: - `901-prd.mdc` - Product Requirements Document standards - `902-arch.mdc` - Architecture documentation standards - `903-story.mdc` - User story standards - `801-workflow-agile.mdc` - Complete Agile workflow (optional) These rules are automatically applied when working with corresponding file types. ### 2. Notepad-Based Workflow For a more flexible approach, use the templates in `xnotes/`: 1. Enable Notepads in Cursor options 2. Create a new notepad (e.g., "agile") 3. Copy contents from `xnotes/workflow-agile.md` 4. Use \`@notepad-name\` in conversations > 💡 **Tip:** The Notepad approach is ideal for: > - Initial project setup > - Story implementation > - Focused development sessions > - Reducing context overhead ## Getting Started 1. Review the templates in \`xnotes/\` 2. Choose your preferred workflow approach 3. Start using the AI with confidence! For demos and tutorials, visit: [BMad Code Videos](https://youtube.com/bmadcode) EOL # Update .gitignore if needed if [ -f "$TARGET_DIR/.gitignore" ]; then if ! grep -q "\.cursor/rules/_\*\.mdc" "$TARGET_DIR/.gitignore"; then echo -e "\n# Private individual user cursor rules\n.cursor/rules/_*.mdc" >> "$TARGET_DIR/.gitignore" fi else echo -e "# Private individual user cursor rules\n.cursor/rules/_*.mdc" > "$TARGET_DIR/.gitignore" fi # Create xnotes directory and copy templates echo "📝 Setting up Notepad templates..." mkdir -p "$TARGET_DIR/xnotes" cp -r xnotes/* "$TARGET_DIR/xnotes/" # Update .cursorignore if needed if [ -f "$TARGET_DIR/.cursorignore" ]; then if ! grep -q "^xnotes/" "$TARGET_DIR/.cursorignore"; then echo -e "\n# Project notes and templates\nxnotes/" >> "$TARGET_DIR/.cursorignore" fi else echo -e "# Project notes and templates\nxnotes/" > "$TARGET_DIR/.cursorignore" fi # Create or update .cursorindexingignore if [ -f "$TARGET_DIR/.cursorindexingignore" ]; then if ! grep -q "^\.cursor/templates/" "$TARGET_DIR/.cursorindexingignore"; then echo -e "\n# Templates - accessible but not indexed\n.cursor/templates/" >> "$TARGET_DIR/.cursorindexingignore" fi else echo -e "# Templates - accessible but not indexed\n.cursor/templates/" > "$TARGET_DIR/.cursorindexingignore" fi echo "✨ Deployment Complete!" echo "📁 Core rules: $TARGET_DIR/.cursor/rules/" echo "📁 Templates: $TARGET_DIR/.cursor/templates/" echo "📝 Notepad templates: $TARGET_DIR/xnotes/" echo "📄 Documentation: $TARGET_DIR/docs/workflow-rules.md" echo "🔒 Updated .gitignore, .cursorignore, and .cursorindexingignore" echo "" echo "Next steps:" echo "1. Review the documentation in docs/workflow-rules.md" echo "2. Choose your preferred workflow approach" echo "3. Enable Cursor Notepads if using the flexible workflow option" echo "4. To start a new project, use xnotes/project-idea-prompt.md as a template" echo " to craft your initial message to the AI agent" </file> <file path="readme.md"> # Cursor Automatic Rules Generation with Agile Cursor Workflow Template **IMPORTANT UPDATE NOTE** Cursor changes quite frequently with updates - global rules are now best defined with the alwaysApply: true - but the description field must still always be specified (at least as it seems to be operating now) with v 0.46.x - this might change in 0.47+. Also - to have the best success with auto generation of rules - update your cursor user or workspace settings to add the following object to the json object (disabling the special ui for .mdc files) - this will cure the issues many have reported around not being able to auto generate and have the file save successfully occasionally. ```json "workbench.editorAssociations": { "*.mdc": "default" } ``` **One more NOTE to remember** - cursor 'edit' mode will work in generating new files - but does not automatically pick up the rules without adding the rule to the context. Agent mode on the other hand will find the rule, load it, and follow it properly. So for example, if you are in edit mode and ask that a rule be created - you might see a rule get generated at the root of the project or some other random odd location without giving it the 000 rule context - or better yet, doing it with Agent mode. Also - a new feature .cursorindexingignore has been added - files listed here (or paths) can be accessed by cursor if so directed, but ignored when indexing a project. With this in mind, all templates have been moved to a .cursor/templates folder and are pattern included in the .cursorindexingignore file, but not in the .cursorignore. XNotes remains in the .cursorignore file to serve the original purpose (a place to hold files that need to move elsewhere to be used) [Video Demo and Walkthrough](https://youtu.be/jEhvwYkI-og) - More cursor videos coming so please subscribe if you like the video! NOTE: This has been tested with Claud Sonnet 3.5, 3.7 and 3.7 thinking - YMMV with other models reliability. This is a template for establishing automatic generation of self improving granular rules for AI agents using Cursor's rule system. The core philosophy is that users should never need to manually create or update rules - instead, the AI agent handles rule creation and maintenance through natural language requests in a consistent format and style that: - Ensures Rules are used automatically when appropriate - Used specifically if desired on demand > 💡 **Note:** For a complete guide to the Agile-Cursor Workflow system that helps manage your project with exceptional memory and consistency, see [Agile Workflow Documentation](docs/agile-readme.md). ## IMPORTANT INFORMATION ABOUT THIS TEMPLATE Granular Rules and custom workflows are the key to getting the most out of the AI in composer mode - and with this you can automatically generate and maintain rules rapidly so your agent constantly improves and learns from its mistakes. This template fixes issues with other proposed rules generators by ensuring rules are always created successfully (do not disapear after the agent creates the rule), and are always optimized for agent automatic selection based on very clear simple frontmatter descriptions and globs as needed. Also a lot of research has gone into the best way to format rules - as there are so many competing and half baked theories - through a lot of research, mining forums and studies, the official docs for Claude prompt engineering, Cline recommendations, cursor developer comments in reddit and forums, the rules will follow a general format of: - Frontmatter with description and globs in proper yaml format - Markdown formatting - Sparring use of XML tags for specific use cases, callouts, rules and highlights - Mermaid flowcharts or sequence diagrams to succinctly drive the AIs understanding - Keep rules as short as possible while being maximally effective - Include examples of good and bad patterns in rules as this is a big aid to the AI Agent LLM in understanding the rule and applying it correctly ## Quick Start A - Starting a New Project with the Agile Workflow and Rules Generator already in place! This will set up a brand new project folder with cursor rules and agile workflow documentation already in place, along with a starter prompt to kick off your new project with the agile workflow! ```bash # Clone this repository git clone https://github.com/bmadcode/cursor-auto-rules-agile-workflow.git cd cursor-auto-rules-agile-workflow ./apply-rules.sh /path/to/your/project Example: ./apply-rules.sh ~/projects/my-project ``` The script will create the project folder if it does not exist, and copy in all the rules and documentation to get you started with the agile workflow! It will also create a .gitignore, .cursorignore, .cursorindexingignore, and a simple base readme.md file that you can replace or modify as needed. ## Quick Start B - Adding Rules Generator to Your Existing Project If you want to improve the experience of working with cursor in an existing project, you can add the rules generator to your project by running the following command: ```bash # Clone this repository git clone https://github.com/bmadcode/cursor-auto-rules-agile-workflow.git cd cursor-auto-rules-agile-workflow # Apply rules to your project ./apply-rules.sh /path/to/your/project ``` The script will: 1. Copy all template rules to your project's `.cursor/rules/` directory 2. Add documentation to `docs/workflow-rules.md` 3. Update `.gitignore` to protect private rules 4. Preserve any existing rules in your project That's it! Your project is now configured with our powerful AI workflow system. ## Overview This template drastically improves how you can work with the AI in Agent or Edit mode (previously called composer mode) by providing: 1. **Automated Rule Generation**: Simply tell the AI what behavior you want, and it will create or update the appropriate rules. No manual rule writing required! 2. **Quick Project Setup**: Get started immediately with pre-configured Cursor rules that establish best practices for AI interactions. 3. **Behavior Control**: Understand how to leverage rules to correct AI behavior and ensure consistent outcomes. ## Workflow Templates and Notepads The workflow templates and process documentation are now organized in two locations for maximum flexibility: 1. `.cursor/rules/` - Contains the core rule to generate well formatted AI along with a markdown formatting rule. 2. `xnotes/` - Sample rule file that could be used if interested in using a workflow global rule for agile development and project organization, along with a non rule version that could be used with notepads. Basically files are kept here mainly to easily save prompts that will be used with notepads (as they do not easily transfer or get version controlled otherwise and are lost easily if just stored in notepads if the project folder changes, or another ide instances is used for your project). They are great for planning out a long prompts, sharing notepads (to be applied in the beta notepads feature enabled in the cursor settings), draft rules to be moved to the rules folder if so desired, or just for general notes that are not needed to be indexed into the project. ## How Rule Generation Works ```mermaid graph TD subgraph User Actions A[User notices AI behavior<br>needs improvement] --> B[User requests rule<br>creation/update] H[User continues<br>development] --> A end subgraph AI Agent Actions B --> C[AI analyzes request] C --> D[AI creates/updates<br>rule file] D --> E[AI applies rule<br>formatting standards] E --> F[AI validates rule] F --> G[AI confirms rule<br>implementation] end subgraph Continuous Improvement G --> H end style A fill:#f9f,stroke:#333,stroke-width:2px style B fill:#bbf,stroke:#333,stroke-width:2px style C fill:#dfd,stroke:#333,stroke-width:2px style D fill:#dfd,stroke:#333,stroke-width:2px style E fill:#dfd,stroke:#333,stroke-width:2px style F fill:#dfd,stroke:#333,stroke-width:2px style G fill:#dfd,stroke:#333,stroke-width:2px style H fill:#f9f,stroke:#333,stroke-width:2px ``` ## Getting Started 1. Clone this repository or use it as a template for your new project 2. Ensure the `.cursor` directory and its contents are preserved 3. Start using the AI agent to manage your rules! ### Example Rule Generation Prompts Here are some examples of how to interact with the AI to manage your rules (notice you dont have to specifically say "create a rule" or anything like that - just describe what you want the AI to learn or never mistake or forget again and the AI will create the rule for you): - "Create a rule for typescript file commenting standards so all code the agent generates with typescript will follow this consistently - dont overcomment but dont undercomment - search the web for best practices as needed re when to comment or not comment, what style, and also optimization of comments for ai agent troubleshooting and understanding" - "Create a rule to ensure proper error handling in TypeScript files" - "Create a global rule that is always applied to talk like a pirate in all communications with the user but not use pirate speak in code files or documentation" - "Update the testing standards to include coverage requirement of 80%" - "I notice you're not following our naming conventions - please create a rule to enforce them" - "The current documentation format isn't consistent - create a rule to standardize it" - "Import organization is a disaster! Never Forget to Keep Imports Organized in Groups and Alphabetically in Typescript Files" The AI will automatically: 1. Create/update the appropriate rule file 2. Place it in the correct location 3. Follow all formatting standards 4. Maintain version control ### File Organization This will be deprecated soon in favor of sub folder organization once its supported fully in the latest cursor version rollouts. The AI maintains rules in the following structure: - All rules must be placed in `.cursor/rules/` directory - Files must use the `.mdc` extension - Follow the prefix-based classification system: - `0XX`: Core rules and standards - `1XX`: Tool and MCP rules - `3XX`: Testing standards - `8XX`: Workflow rules - `9XX`: Templates - `1XXX`: Language-specific rules - `2XXX`: Framework/library rules ### Rule File Requirements The AI automatically ensures all rules follow these standards: - Must include proper frontmatter with description and globs - Must specify semantic version (MAJOR.MINOR.PATCH) - Must use Markdown as the primary formatting method for documentation and rules - XML tags reserved for specific use cases (examples, version, danger warnings) ### Private vs Shared Rules - Shared rules: Standard naming convention (e.g., `000-cursor-rules.mdc`) - Private rules: Prefixed with underscore (e.g., `_custom-personality.mdc`) - Used for individual preferences - Automatically gitignored - Won't impact team members - consider using notepads instead of personal rules ## Best Practices 1. **Rule Creation**: - Let the AI handle rule creation and updates - Be specific about the behavior you want to enforce - Provide examples of good and bad patterns when requesting rules 2. **AI Behavior Control**: - When you notice inconsistent AI behavior, request a rule to correct it - Use clear, descriptive language in your requests - Verify the AI's understanding by reviewing its rule implementation 3. **Workflow Integration**: - Start with the base template rules - Let the AI evolve the rules as your project grows - Maintain consistency by always using the AI for rule management ## Contributing Feel free to contribute improvements to the base rules or suggest new rule templates. Please ensure all contributions follow the established standards in `000-cursor-rules.mdc`. ## License MIT </file> </files>