--- description: Meta-rule for creating new rules and subagents. Ensures all new rules follow YAML frontmatter and folder structure from official Cursor documentation. Triggered when user asks to 'create a new rule' or 'create a new subagent'. globs: .cursor/**/* alwaysApply: false --- # Meta-Rule: Rule & Subagent Generator ## Purpose This rule ensures that all new rules and subagents follow the official [Cursor Subagents Documentation](https://cursor.com/docs/context/subagents) specifications, while strictly adhering to SuiteX's **Centralized AI Rule Architecture**. --- ## 🚦 Decision Tree: Rule vs Subagent ### When to Create a RULE (`docs/ai-rules/*.md`) Create a **Rule** if the content is: - ✅ **Standards** - Coding conventions, architecture patterns - ✅ **Conventions** - Naming standards, file organization - ✅ **Prohibitions** - "Never do X" statements - ✅ **Always-on context** - Should be auto-loaded based on file patterns - ✅ **Reference material** - Documentation that informs decisions **Examples:** - Security validation patterns - Testing standards (Pest syntax, SQLite setup) - Performance rules (N+1 prevention, caching) - Architecture guidelines (DDD, service placement) ### When to Create a SUBAGENT (`.agent/workflows/*.md`) Create a **Subagent** if the content is: - ✅ **Multi-step workflow** - Orchestrates complex tasks - ✅ **Autonomous specialist** - Handles specific domain independently - ✅ **Task executor** - Runs tests, generates files, reviews code - ✅ **Delegation target** - Can be invoked explicitly with `/name` - ✅ **Context-isolated** - Needs separate context window **Examples:** - Test writer (creates test files) - Bug coordinator (orchestrates debugging) - Code reviewer (performs PR review) - Jira architect (creates tickets) --- ## 🚨 MANDATORY ARCHITECTURE: The Pointer System When asked to create a new rule or agent in Cursor, you **MUST NOT** put the logic directly in Cursor folders. You must create the Core Logic in the Central Vault, and then create a "Pointer" in the IDE folder. ### For RULES: 1. **Core Logic:** Write the full markdown file in `docs/ai-rules/NNN-name.md`. 2. **The IDE Pointer:** Create `.cursor/rules/NNN-name.mdc` using the Pointer Template. ### For SUBAGENTS: 1. **Core Logic:** Write the full markdown file in `.agent/workflows/name.md`. 2. **The IDE Pointer:** Create `.cursor/agents/name.md` using the Pointer Template. --- ## 📋 The "Pointer" Templates (For `.cursor` folders) ### Rule Pointer (`.cursor/rules/*.mdc`) ```markdown --- description: Auto-routes to central [name] rule repository globs: [File patterns, comma-separated e.g. **/*.php] alwaysApply: false --- # 🚨 CENTRAL REPOSITORY POINTER 🚨 This file is a POINTER. The definitive rules for this domain are located in the central vault. **You MUST read the following file before proceeding:** `docs/ai-rules/[filename].md` ``` ### Agent Pointer (`.cursor/agents/*.md`) ```markdown --- name: [agent-slug] description: [Brief description] model: inherit --- # 🚨 CENTRAL REPOSITORY POINTER 🚨 You operate under the global architecture of SuiteX. To execute your specialist role correctly, you MUST read the central workflow definition for this agent. **READ THIS FILE BEFORE PROCEEDING:** `.agent/workflows/[agent-slug].md` ``` --- ## 📋 Core RULE Template (`docs/ai-rules/*.md`) ### File Naming Convention - **Pattern:** `NNN-category-name.md` (e.g., `600-database-standards.md`) - **Numbering:** Use hundreds (000, 100, 200, etc.) for ordering ### Complete Rule Template ```markdown # [Rule Title] ## Overview [Brief explanation of why this rule exists] ## Standards ### 1. [Standard Name] **Rule:** [Clear statement of the standard] **✅ GOOD:** ```[language] [Example of correct implementation] ``` **❌ BAD:** ```[language] [Example of incorrect implementation] ``` ### 2. [Another Standard] [Continue pattern...] ## Prohibitions **NEVER** [specific action to avoid] **ALWAYS** [required action] ## Validation Checklist - [ ] [Verification step 1] - [ ] [Verification step 2] ``` --- ## 📋 Core SUBAGENT Template (`.agent/workflows/*.md`) ### File Naming Convention - **Pattern:** `agent-name.md` (e.g., `security-reviewer.md`) - **Format:** kebab-case (all lowercase, hyphens between words) ### Complete Workflow Template ```markdown # Agent: [Display Name] ### **Context** You are the **[Role Title]**. Your goal is [primary objective]. **Critical Instruction:** [Any mandatory reading or setup] ### **Workflow** **Step 1: [Phase Name]** * **Action:** [What to do] * **Tool:** [Command or method] * **Output:** [Expected result] **Step 2: [Next Phase]** * **Action:** [What to do] * **Verification:** [How to validate] **Step 3: [Final Phase]** * **Deliverable:** [What to produce] --- ### **Response Format** ```markdown ## [Report Title] ### [Section 1] * **[Field]:** [Value] ### [Section 2] [Content] ``` ``` --- ## 📁 Centralized Directory Structure ``` SuiteX/ ├── docs/ai-rules/ # CORE Standards & Conventions (*.md) │ ├── 000-core-standards.md │ ├── 100-backend-laravel.md │ └── meta-rule-generator.md (THIS FILE) │ ├── .agent/workflows/ # CORE Task Executors (*.md) │ ├── test-writer.md │ └── bug-coordinator.md │ └── .cursor/ # IDE Pointers ├── rules/ # Pure Pointers to docs/ai-rules (*.mdc) │ └── 100-backend.mdc └── agents/ # Pure Pointers to .agent/workflows (*.md) └── test-writer.md ``` --- ## 🚀 Creation Workflow ### When User Requests: "Create a new rule" 1. **Clarify Intent** - Ask: "Is this a **standard/convention** (Rule) or a **workflow/task** (Subagent)?" 2. **Gather Requirements** - For Rules: What standards? Which file types? - For Subagents: What task? When to invoke? What's the workflow? 3. **Generate Core Logic** - Write the full markdown rule into `docs/ai-rules/` OR full workflow into `.agent/workflows/` 4. **Generate IDE Pointer** - Create the corresponding `.mdc` or `.md` pointer file inside `.cursor/` using the pointer templates. 5. **Update Main Config (if Subagent)** - Add entry to `.cursorrules` subagent table - Describe purpose in table --- ## 🔧 Common Mistakes to Avoid ### ❌ WRONG: Mixed Formats ```yaml --- name: Test Standards description: Testing rules globs: **/*.php --- ``` **Issue:** Rules don't use `name` field; Subagents don't use `globs` ### ✅ CORRECT: Rule Format ```yaml --- description: Testing standards for Pest and SQLite patterns globs: tests/**/*.php alwaysApply: false --- ``` ### ❌ WRONG: Improper Naming - `Test Writer.md` (spaces in filename) - `TestWriter.md` (PascalCase) - `test_writer.md` (snake_case) - `testing-rules.md` (rule in agents folder) ### ✅ CORRECT: Naming - `.agent/workflows/test-writer.md` (subagent, kebab-case) - `.agent/rules/400-testing.md` (rule, numbered) ### ❌ WRONG: Description ```yaml description: A helper that does things ``` **Issue:** Vague, no usage guidance, includes article ### ✅ CORRECT: Description ```yaml description: Test automation expert. Use proactively to run tests and fix failures when code changes are made. ``` --- ## 📚 Reference Documentation - **Official Cursor Docs:** https://cursor.com/docs/context/subagents - **Project Refactor Summary:** `.cursor/REFACTOR_SUMMARY.md` - **Quick Reference:** `.cursor/SUBAGENT_REFERENCE.md` - **Main Config:** `.cursorrules` --- ## ✅ Post-Creation Steps After creating a new rule or subagent: ### For Rules 1. Test glob patterns match intended files 2. Verify rule loads in appropriate contexts 3. Check for conflicts with existing rules 4. Update team documentation if needed ### For Subagents 1. Add entry to `.cursorrules` table 2. Test invocation with `/agent-name` 3. Verify workflow executes correctly 4. Update `.cursor/SUBAGENT_REFERENCE.md` if needed 5. Ensure description enables proactive delegation --- ## 💡 Best Practices 1. **Be Specific:** Vague rules/subagents are rarely used effectively 2. **Include Examples:** Show correct vs incorrect patterns 3. **Test First:** Verify the rule/subagent works before committing 4. **Document Usage:** Clear descriptions enable better delegation 5. **Avoid Duplication:** Check existing rules/subagents first 6. **Keep Focused:** One clear purpose per rule/subagent 7. **Use Conventions:** Follow existing naming and structure patterns