forked from jsnbuchanan/crowd-funder-for-time-pwa
refactor(cursor-rules): restructure rules architecture with meta-rule system
- Reorganize cursor rules into logical domain-based directories - Implement meta-rule system for workflow-specific rule bundling - Move core rules to dedicated /core directory - Consolidate development rules under /development namespace - Add architectural patterns and implementation examples - Create workflow-specific meta-rules for common development tasks - Remove deprecated standalone rule files - Update package dependencies for new rule structure BREAKING CHANGE: Cursor rules file structure has been reorganized Files moved from root rules directory to domain-specific subdirectories
This commit is contained in:
Matthew Raymer
175
.cursor/rules/docs/markdown_core.mdc
Normal file
175
.cursor/rules/docs/markdown_core.mdc
Normal file
@@ -0,0 +1,175 @@
|
||||
# Markdown Core Standards & Automation
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-21
|
||||
**Status**: 🎯 **ACTIVE** - Core markdown standards and automation
|
||||
|
||||
## Overview
|
||||
|
||||
This file combines core markdown formatting standards with automation
|
||||
guidelines. AI agents must follow these rules DURING content generation,
|
||||
not apply them after the fact.
|
||||
|
||||
## AI Generation Guidelines
|
||||
|
||||
### **MANDATORY**: Follow These Rules While Writing
|
||||
|
||||
When generating markdown content, you MUST:
|
||||
|
||||
1. **Line Length**: Never exceed 80 characters per line
|
||||
2. **Blank Lines**: Always add blank lines around headings, lists, and
|
||||
code blocks
|
||||
3. **Structure**: Use proper heading hierarchy and document templates
|
||||
4. **Formatting**: Apply consistent formatting patterns immediately
|
||||
|
||||
### **DO NOT**: Generate content that violates these rules
|
||||
|
||||
- ❌ Generate long lines that need breaking
|
||||
- ❌ Create content without proper blank line spacing
|
||||
- ❌ Use inconsistent formatting patterns
|
||||
- ❌ Assume post-processing will fix violations
|
||||
|
||||
### **DO**: Generate compliant content from the start
|
||||
|
||||
- ✅ Write within 80-character limits
|
||||
- ✅ Add blank lines around all structural elements
|
||||
- ✅ Use established templates and patterns
|
||||
- ✅ Apply formatting standards immediately
|
||||
|
||||
## Core Formatting Standards
|
||||
|
||||
### Line Length
|
||||
|
||||
- **Maximum line length**: 80 characters
|
||||
- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line
|
||||
length enforcement
|
||||
- **Rationale**: Ensures readability across different screen sizes and
|
||||
terminal widths
|
||||
|
||||
### Blank Lines
|
||||
|
||||
- **Headings**: Must be surrounded by blank lines above and below
|
||||
- **Lists**: Must be surrounded by blank lines above and below
|
||||
- **Code blocks**: Must be surrounded by blank lines above and below
|
||||
- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
|
||||
- **File start**: No blank lines at the beginning of the file
|
||||
- **File end**: Single newline character at the end
|
||||
|
||||
### Whitespace
|
||||
|
||||
- **No trailing spaces**: Remove all trailing whitespace from lines
|
||||
- **No tabs**: Use spaces for indentation
|
||||
- **Consistent indentation**: 2 spaces for list items and nested content
|
||||
|
||||
## Heading Standards
|
||||
|
||||
### Format
|
||||
|
||||
- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
|
||||
- **Case**: Title case for general headings
|
||||
- **Code references**: Use backticks for file names and technical terms
|
||||
- ✅ `### Current package.json Scripts`
|
||||
- ❌ `### Current Package.json Scripts`
|
||||
|
||||
### Hierarchy
|
||||
|
||||
- **H1 (#)**: Document title only
|
||||
- **H2 (##)**: Major sections
|
||||
- **H3 (###)**: Subsections
|
||||
- **H4 (####)**: Sub-subsections
|
||||
- **H5+**: Avoid deeper nesting
|
||||
|
||||
## List Standards
|
||||
|
||||
### Unordered Lists
|
||||
|
||||
- **Marker**: Use `-` (hyphen) consistently
|
||||
- **Indentation**: 2 spaces for nested items
|
||||
- **Blank lines**: Surround lists with blank lines
|
||||
|
||||
### Ordered Lists
|
||||
|
||||
- **Format**: `1.`, `2.`, `3.` (sequential numbering)
|
||||
- **Indentation**: 2 spaces for nested items
|
||||
- **Blank lines**: Surround lists with blank lines
|
||||
|
||||
### Task Lists
|
||||
|
||||
- **Format**: `- [ ]` for incomplete, `- [x]` for complete
|
||||
- **Indentation**: 2 spaces for nested items
|
||||
- **Blank lines**: Surround lists with blank lines
|
||||
|
||||
## Code Block Standards
|
||||
|
||||
### Inline Code
|
||||
|
||||
- **Format**: Single backticks for inline code
|
||||
- **Use cases**: File names, commands, variables, technical terms
|
||||
- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM`
|
||||
|
||||
### Code Blocks
|
||||
|
||||
- **Format**: Triple backticks with language specification
|
||||
- **Language**: Always specify the language for syntax highlighting
|
||||
- **Blank lines**: Surround with blank lines above and below
|
||||
|
||||
## Automation System
|
||||
|
||||
### Available Commands
|
||||
|
||||
- **`npm run markdown:fix`** - Fix formatting in all markdown files
|
||||
using markdownlint-cli2 --fix
|
||||
- **`npm run markdown:check`** - Validate formatting without fixing
|
||||
using markdownlint-cli2
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **AI Agent Compliance** (Primary): AI follows markdown rules during
|
||||
generation
|
||||
2. **Pre-commit Hooks** (Backup): Catches any remaining formatting
|
||||
issues
|
||||
3. **GitHub Actions** (Pre-merge): Validates formatting before merge
|
||||
|
||||
### Benefits
|
||||
|
||||
- **No more manual fixes** - AI generates compliant content from start
|
||||
- **Consistent style** - All files follow same standards
|
||||
- **Faster development** - No need to fix formatting manually
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Generating Markdown Content
|
||||
|
||||
- [ ] **Line Length**: Ensure no line exceeds 80 characters
|
||||
- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks
|
||||
- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation
|
||||
- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only)
|
||||
- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered)
|
||||
- [ ] **Code**: Specify language for fenced blocks, use backticks for inline
|
||||
|
||||
### After Generating Markdown Content
|
||||
|
||||
- [ ] **Validation**: Run `npm run markdown:check` to verify compliance
|
||||
- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found
|
||||
- [ ] **Review**: Confirm content follows established templates and patterns
|
||||
- [ ] **Cross-reference**: Link to related documentation and templates
|
||||
|
||||
### Quality Assurance
|
||||
|
||||
- [ ] **Readability**: Content is clear and follows project conventions
|
||||
- [ ] **Consistency**: Formatting matches existing documentation style
|
||||
- [ ] **Completeness**: All required sections and information included
|
||||
- [ ] **Accuracy**: Technical details are correct and up-to-date
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates
|
||||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
|
||||
|
||||
**Status**: Active core standards and automation
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Documentation team, Development team
|
||||
Reference in New Issue
Block a user