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
@@ -1,14 +1,37 @@
|
||||
---
|
||||
alwaysApply: true
|
||||
alwaysApply: false
|
||||
---
|
||||
# Directive for Documentation Generation
|
||||
|
||||
1. Produce a **small, focused set of documents** rather than an overwhelming volume.
|
||||
2. Ensure the content is **maintainable and worth preserving**, so that humans
|
||||
are motivated to keep it up to date.
|
||||
are motivated to keep it up to date.
|
||||
3. Prioritize **educational value**: the documents must clearly explain the
|
||||
workings of the system.
|
||||
4. Avoid **shallow, generic, or filler explanations** often found in
|
||||
AI-generated documentation.
|
||||
workings of the system.
|
||||
4. Avoid **shallow, generic, or filler explanations** often found in AI-generated
|
||||
documentation.
|
||||
5. Aim for **clarity, depth, and usefulness**, so readers gain genuine understanding.
|
||||
6. Always check the local system date to determine current date.
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Documentation Creation
|
||||
|
||||
- [ ] **Scope Definition**: Define what needs to be documented
|
||||
- [ ] **Audience Analysis**: Identify target readers and their needs
|
||||
- [ ] **Content Planning**: Plan focused, educational content structure
|
||||
- [ ] **Maintenance Planning**: Ensure content will be worth preserving
|
||||
|
||||
### During Documentation Creation
|
||||
|
||||
- [ ] **Educational Focus**: Clearly explain how the system works
|
||||
- [ ] **Depth and Clarity**: Provide genuine understanding, not surface explanations
|
||||
- [ ] **Focused Content**: Keep documents small and focused on specific topics
|
||||
- [ ] **Current Date**: Check local system date for time-sensitive content
|
||||
|
||||
### After Documentation Creation
|
||||
|
||||
- [ ] **Quality Review**: Ensure content is clear, deep, and useful
|
||||
- [ ] **Maintainability Check**: Verify content motivates humans to keep it updated
|
||||
- [ ] **Audience Validation**: Confirm content meets target reader needs
|
||||
- [ ] **Integration**: Integrate with existing documentation structure
|
||||
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# Markdown Automation System
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-20
|
||||
**Status**: 🎯 **ACTIVE** - Markdown formatting automation
|
||||
|
||||
## Overview
|
||||
|
||||
The Markdown Automation System ensures your markdown formatting standards are
|
||||
followed **during content generation** by AI agents, not just applied after the
|
||||
fact.
|
||||
|
||||
## AI-First Approach
|
||||
|
||||
### **Primary Method**: AI Agent Compliance
|
||||
|
||||
- **AI agents follow markdown rules** while generating content
|
||||
- **No post-generation fixes needed** - content is compliant from creation
|
||||
- **Consistent formatting** across all generated documentation
|
||||
|
||||
### **Secondary Method**: Automated Validation
|
||||
|
||||
- **Pre-commit hooks** catch any remaining issues
|
||||
- **GitHub Actions** validate formatting before merge
|
||||
- **Manual tools** for bulk fixes when needed
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. **AI Agent Compliance** (Primary)
|
||||
|
||||
- **When**: Every time AI generates markdown content
|
||||
- **What**: AI follows markdown rules during generation
|
||||
- **Result**: Content is properly formatted from creation
|
||||
|
||||
### 2. **Pre-commit Hooks** (Backup)
|
||||
|
||||
- **When**: Every time you commit
|
||||
- **What**: Catches any remaining formatting issues
|
||||
- **Result**: Clean, properly formatted markdown files
|
||||
|
||||
### 3. **GitHub Actions** (Pre-merge)
|
||||
|
||||
- **When**: Every pull request
|
||||
- **What**: Validates markdown formatting across all files
|
||||
- **Result**: Blocks merge if formatting issues exist
|
||||
|
||||
## AI Agent Rules Integration
|
||||
|
||||
The AI agent follows markdown rules defined in `.cursor/rules/docs/markdown.mdc`:
|
||||
|
||||
- **alwaysApply: true** - Rules are enforced during generation
|
||||
- **Line Length**: AI never generates lines > 80 characters
|
||||
- **Blank Lines**: AI adds proper spacing around all elements
|
||||
- **Structure**: AI uses established templates and patterns
|
||||
|
||||
## Available Commands
|
||||
|
||||
### NPM Scripts
|
||||
|
||||
- **`npm run markdown:setup`** - Install the automation system
|
||||
- **`npm run markdown:fix`** - Fix formatting in all markdown files
|
||||
- **`npm run markdown:check`** - Validate formatting without fixing
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active automation system
|
||||
**Priority**: High
|
||||
**Maintainer**: Development team
|
||||
**Next Review**: 2025-09-20
|
||||
@@ -1,366 +0,0 @@
|
||||
---
|
||||
globs: ["*.md", "*.mdc"]
|
||||
alwaysApply: false
|
||||
---
|
||||
# Cursor Markdown Ruleset for TimeSafari Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
This ruleset enforces consistent markdown formatting standards across all project
|
||||
documentation, ensuring readability, maintainability, and compliance with
|
||||
markdownlint best practices.
|
||||
|
||||
**⚠️ CRITICAL FOR AI AGENTS**: These rules must be followed DURING content
|
||||
generation, not applied after the fact. Always generate markdown that complies
|
||||
with these standards from the start.
|
||||
|
||||
## 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
|
||||
|
||||
## General 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
|
||||
- **Use case**: Project planning, checklists, implementation tracking
|
||||
|
||||
## Code Block Standards
|
||||
|
||||
### Fenced Code Blocks
|
||||
|
||||
- **Syntax**: Triple backticks with language specification
|
||||
- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown`
|
||||
- **Blank lines**: Must be surrounded by blank lines above and below
|
||||
- **Line length**: No enforcement within code blocks
|
||||
|
||||
### Inline Code
|
||||
|
||||
- **Format**: Single backticks for inline code references
|
||||
- **Use case**: File names, commands, variables, properties
|
||||
|
||||
## Special Content Standards
|
||||
|
||||
### JSON Examples
|
||||
|
||||
```json
|
||||
{
|
||||
"property": "value",
|
||||
"nested": {
|
||||
"property": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Shell Commands
|
||||
|
||||
```bash
|
||||
# Command with comment
|
||||
npm run build:web
|
||||
|
||||
# Multi-line command
|
||||
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
|
||||
vite build --config vite.config.web.mts
|
||||
```
|
||||
|
||||
### TypeScript Examples
|
||||
|
||||
```typescript
|
||||
// Function with JSDoc
|
||||
/**
|
||||
* Get environment configuration
|
||||
* @param env - Environment name
|
||||
* @returns Environment config object
|
||||
*/
|
||||
const getEnvironmentConfig = (env: string) => {
|
||||
switch (env) {
|
||||
case 'prod':
|
||||
return { /* production settings */ };
|
||||
default:
|
||||
return { /* development settings */ };
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## File Structure Standards
|
||||
|
||||
### Document Header
|
||||
|
||||
```markdown
|
||||
# Document Title
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: 🎯 **STATUS** - Brief description
|
||||
|
||||
## Overview
|
||||
|
||||
Brief description of the document's purpose and scope.
|
||||
```
|
||||
|
||||
### Section Organization
|
||||
|
||||
1. **Overview/Introduction**
|
||||
2. **Current State Analysis**
|
||||
3. **Implementation Plan**
|
||||
4. **Technical Details**
|
||||
5. **Testing & Validation**
|
||||
6. **Next Steps**
|
||||
|
||||
## Markdownlint Configuration
|
||||
|
||||
### Required Rules
|
||||
|
||||
```json
|
||||
{
|
||||
"MD013": { "code_blocks": false },
|
||||
"MD012": true,
|
||||
"MD022": true,
|
||||
"MD031": true,
|
||||
"MD032": true,
|
||||
"MD047": true,
|
||||
"MD009": true
|
||||
}
|
||||
```
|
||||
|
||||
### Rule Explanations
|
||||
|
||||
- **MD013**: Line length (disabled for code blocks)
|
||||
- **MD012**: No multiple consecutive blank lines
|
||||
- **MD022**: Headings should be surrounded by blank lines
|
||||
- **MD031**: Fenced code blocks should be surrounded by blank lines
|
||||
- **MD032**: Lists should be surrounded by blank lines
|
||||
- **MD047**: Files should end with a single newline
|
||||
- **MD009**: No trailing spaces
|
||||
|
||||
## Validation Commands
|
||||
|
||||
### Check Single File
|
||||
|
||||
```bash
|
||||
npx markdownlint docs/filename.md
|
||||
```
|
||||
|
||||
### Check All Documentation
|
||||
|
||||
```bash
|
||||
npx markdownlint docs/
|
||||
```
|
||||
|
||||
### Auto-fix Common Issues
|
||||
|
||||
```bash
|
||||
# Remove trailing spaces
|
||||
sed -i 's/[[:space:]]*$//' docs/filename.md
|
||||
|
||||
# Remove multiple blank lines
|
||||
sed -i '/^$/N;/^\n$/D' docs/filename.md
|
||||
|
||||
# Add newline at end if missing
|
||||
echo "" >> docs/filename.md
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Implementation Plans
|
||||
|
||||
```markdown
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation (Day 1)
|
||||
|
||||
#### 1.1 Component Setup
|
||||
|
||||
- [ ] Create new component file
|
||||
- [ ] Add basic structure
|
||||
- [ ] Implement core functionality
|
||||
|
||||
#### 1.2 Configuration
|
||||
|
||||
- [ ] Update configuration files
|
||||
- [ ] Add environment variables
|
||||
- [ ] Test configuration loading
|
||||
```
|
||||
|
||||
### Status Tracking
|
||||
|
||||
```markdown
|
||||
**Status**: ✅ **COMPLETE** - All phases finished
|
||||
**Progress**: 75% (15/20 components)
|
||||
**Next**: Ready for testing phase
|
||||
```
|
||||
|
||||
### Performance Metrics
|
||||
|
||||
```markdown
|
||||
#### 📊 Performance Metrics
|
||||
- **Build Time**: 2.3 seconds (50% faster than baseline)
|
||||
- **Bundle Size**: 1.2MB (30% reduction)
|
||||
- **Success Rate**: 100% (no failures in 50 builds)
|
||||
```
|
||||
|
||||
## Enforcement
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
- Run markdownlint on all changed markdown files
|
||||
- Block commits with linting violations
|
||||
- Auto-fix common issues when possible
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
- Include markdownlint in build pipeline
|
||||
- Generate reports for documentation quality
|
||||
- Fail builds with critical violations
|
||||
|
||||
### Team Guidelines
|
||||
|
||||
- All documentation PRs must pass markdownlint
|
||||
- Use provided templates for new documents
|
||||
- Follow established patterns for consistency
|
||||
|
||||
## Templates
|
||||
|
||||
### New Document Template
|
||||
|
||||
```markdown
|
||||
# Document Title
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: 🎯 **PLANNING** - Ready for Implementation
|
||||
|
||||
## Overview
|
||||
|
||||
Brief description of the document's purpose and scope.
|
||||
|
||||
## Current State
|
||||
|
||||
Description of current situation or problem.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation
|
||||
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review and approve plan**
|
||||
2. **Begin implementation**
|
||||
3. **Test and validate**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for implementation
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: X days
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-07-09
|
||||
**Version**: 1.0
|
||||
**Maintainer**: Matthew Raymer
|
||||
|
||||
|
||||
### Heading Uniqueness
|
||||
|
||||
- **Rule**: No duplicate heading content at the same level
|
||||
- **Scope**: Within a single document
|
||||
- **Rationale**: Maintains clear document structure and navigation
|
||||
- **Example**:
|
||||
|
||||
```markdown
|
||||
## Features ✅
|
||||
### Authentication
|
||||
### Authorization
|
||||
|
||||
## Features ❌ (Duplicate heading)
|
||||
### Security
|
||||
### Performance
|
||||
```
|
||||
## Features ❌ (Duplicate heading)
|
||||
### Security
|
||||
### Performance
|
||||
```
|
||||
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
|
||||
219
.cursor/rules/docs/markdown_templates.mdc
Normal file
219
.cursor/rules/docs/markdown_templates.mdc
Normal file
@@ -0,0 +1,219 @@
|
||||
# Markdown Templates & Examples
|
||||
|
||||
> **Agent role**: Reference this file for document templates, structure,
|
||||
> and examples when creating new documentation.
|
||||
|
||||
## Document Templates
|
||||
|
||||
### Standard Document Template
|
||||
|
||||
```markdown
|
||||
# Document Title
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: 🎯 **STATUS** - Brief description
|
||||
|
||||
## Overview
|
||||
|
||||
Brief description of the document's purpose and scope.
|
||||
|
||||
## Current State
|
||||
|
||||
Description of current situation or problem.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Foundation
|
||||
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Review and approve plan**
|
||||
2. **Begin implementation**
|
||||
3. **Test and validate**
|
||||
|
||||
---
|
||||
|
||||
**Status**: Ready for implementation
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: X days
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team
|
||||
```
|
||||
|
||||
### Technical Specification Template
|
||||
|
||||
```markdown
|
||||
# Technical Specification: [Feature Name]
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: 🎯 **DRAFT** - Under Review
|
||||
|
||||
## Overview
|
||||
|
||||
Brief description of the technical specification.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- [ ] Requirement 1
|
||||
- [ ] Requirement 2
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- [ ] Performance requirement
|
||||
- [ ] Security requirement
|
||||
|
||||
## Technical Design
|
||||
|
||||
### Architecture
|
||||
|
||||
Description of the technical architecture.
|
||||
|
||||
### Data Models
|
||||
|
||||
```typescript
|
||||
interface ExampleModel {
|
||||
id: string;
|
||||
name: string;
|
||||
createdAt: Date;
|
||||
}
|
||||
```
|
||||
|
||||
### API Design
|
||||
|
||||
```typescript
|
||||
interface APIResponse<T> {
|
||||
success: boolean;
|
||||
data: T;
|
||||
error?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- [ ] Unit tests
|
||||
- [ ] Integration tests
|
||||
- [ ] E2E tests
|
||||
|
||||
---
|
||||
|
||||
**Status**: Draft
|
||||
**Priority**: High
|
||||
**Estimated Effort**: X days
|
||||
**Dependencies**: None
|
||||
**Stakeholders**: Development team
|
||||
|
||||
```
|
||||
|
||||
## Content Examples
|
||||
|
||||
### JSON Examples
|
||||
|
||||
```json
|
||||
{
|
||||
"property": "value",
|
||||
"nested": {
|
||||
"property": "value"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Shell Commands
|
||||
|
||||
```bash
|
||||
# Command with comment
|
||||
npm run build:web
|
||||
|
||||
# Multi-line command
|
||||
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
|
||||
vite build --config vite.config.web.mts
|
||||
```
|
||||
|
||||
### TypeScript Examples
|
||||
|
||||
```typescript
|
||||
// Function with JSDoc
|
||||
const getEnvironmentConfig = (env: string) => {
|
||||
switch (env) {
|
||||
case 'prod':
|
||||
return { /* production settings */ };
|
||||
default:
|
||||
return { /* development settings */ };
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
## File Structure Standards
|
||||
|
||||
### Document Header
|
||||
|
||||
```markdown
|
||||
# Document Title
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: YYYY-MM-DD
|
||||
**Status**: 🎯 **STATUS** - Brief description
|
||||
|
||||
## Overview
|
||||
|
||||
Brief description of the document's purpose and scope.
|
||||
```
|
||||
|
||||
### Section Organization
|
||||
|
||||
Standard sections: Overview, Current State, Implementation Plan,
|
||||
Technical Details, Testing & Validation, Next Steps
|
||||
|
||||
## Common Patterns
|
||||
|
||||
Standard implementation plans follow Phase 1 (Foundation), Phase 2
|
||||
(Features), Phase 3 (Testing & Polish) structure.
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Using Templates
|
||||
|
||||
- [ ] **Template Selection**: Choose appropriate template for document type
|
||||
- [ ] **Structure Review**: Understand required sections and organization
|
||||
- [ ] **Content Planning**: Plan what information goes in each section
|
||||
- [ ] **Audience Analysis**: Ensure template matches target audience needs
|
||||
|
||||
### During Template Usage
|
||||
|
||||
- [ ] **Section Completion**: Fill in all required sections completely
|
||||
- [ ] **Example Integration**: Include relevant code examples and patterns
|
||||
- [ ] **Formatting Consistency**: Apply markdown standards from core rules
|
||||
- [ ] **Cross-references**: Link to related documentation and resources
|
||||
|
||||
### After Template Usage
|
||||
|
||||
- [ ] **Content Review**: Verify all sections contain appropriate content
|
||||
- [ ] **Formatting Check**: Run `npm run markdown:check` for compliance
|
||||
- [ ] **Template Validation**: Confirm document follows template structure
|
||||
- [ ] **Quality Assessment**: Ensure content meets project standards
|
||||
|
||||
### Template-Specific Requirements
|
||||
|
||||
- [ ] **Standard Documents**: Include all required metadata and sections
|
||||
- [ ] **Technical Specs**: Complete all requirement and design sections
|
||||
- [ ] **Implementation Plans**: Define clear phases and milestones
|
||||
- [ ] **Examples**: Provide relevant, working code examples
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
|
||||
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows
|
||||
|
||||
**Status**: Active templates and examples
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: markdown_core.mdc
|
||||
**Stakeholders**: Documentation team, Development team
|
||||
168
.cursor/rules/docs/markdown_workflow.mdc
Normal file
168
.cursor/rules/docs/markdown_workflow.mdc
Normal file
@@ -0,0 +1,168 @@
|
||||
# Markdown Workflow & Validation
|
||||
|
||||
> **Agent role**: Reference this file for markdown validation rules,
|
||||
> enforcement procedures, and workflow management.
|
||||
|
||||
## Markdownlint Configuration
|
||||
|
||||
### Core Rules
|
||||
|
||||
```json
|
||||
{
|
||||
"MD013": { "line_length": 80, "code_blocks": false },
|
||||
"MD012": true,
|
||||
"MD022": true,
|
||||
"MD031": true,
|
||||
"MD032": true,
|
||||
"MD047": true,
|
||||
"MD009": true,
|
||||
"MD004": { "style": "dash" }
|
||||
}
|
||||
```
|
||||
|
||||
### Rule Explanations
|
||||
|
||||
- **MD013**: Line length (80 chars, disabled for code blocks)
|
||||
- **MD012**: No multiple consecutive blank lines
|
||||
- **MD022**: Headings should be surrounded by blank lines
|
||||
- **MD031**: Fenced code blocks should be surrounded by blank lines
|
||||
- **MD032**: Lists should be surrounded by blank lines
|
||||
- **MD047**: Files should end with a single newline
|
||||
- **MD009**: No trailing spaces
|
||||
- **MD004**: Consistent list markers (dash style)
|
||||
|
||||
## Validation Commands
|
||||
|
||||
### Check All MDC Files
|
||||
|
||||
```bash
|
||||
npm run markdown:check
|
||||
```
|
||||
|
||||
### Auto-fix Formatting Issues
|
||||
|
||||
```bash
|
||||
npm run markdown:fix
|
||||
```
|
||||
|
||||
### Check Single File
|
||||
|
||||
```bash
|
||||
npx markdownlint-cli2 .cursor/rules/filename.mdc
|
||||
```
|
||||
|
||||
## Enforcement Workflow
|
||||
|
||||
### Pre-commit Hooks
|
||||
|
||||
- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all
|
||||
staged `.mdc` files
|
||||
- **Result**: Files are automatically formatted before commit
|
||||
- **Blocking**: Commits with unfixable violations are blocked
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
- **Build Pipeline**: Include markdownlint in automated builds
|
||||
- **Quality Reports**: Generate documentation quality metrics
|
||||
- **Build Failure**: Fail builds with critical violations
|
||||
|
||||
### Team Guidelines
|
||||
|
||||
- **PR Requirements**: All documentation PRs must pass markdownlint
|
||||
- **Templates**: Use provided templates for new documents
|
||||
- **Patterns**: Follow established patterns for consistency
|
||||
- **Auto-fixing**: Let automation handle formatting, focus on content
|
||||
|
||||
## Quality Assurance
|
||||
|
||||
### Validation Checklist
|
||||
|
||||
- [ ] All files pass `npm run markdown:check`
|
||||
- [ ] Line length under 80 characters
|
||||
- [ ] Proper blank line spacing around elements
|
||||
- [ ] No trailing spaces
|
||||
- [ ] Consistent list markers
|
||||
- [ ] Proper heading hierarchy
|
||||
- [ ] Code blocks have language specification
|
||||
|
||||
### Common Issues & Fixes
|
||||
|
||||
#### Trailing Spaces
|
||||
|
||||
```bash
|
||||
# Remove trailing spaces
|
||||
sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc
|
||||
```
|
||||
|
||||
#### Multiple Blank Lines
|
||||
|
||||
```bash
|
||||
# Remove multiple blank lines
|
||||
sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc
|
||||
```
|
||||
|
||||
#### Missing Newlines
|
||||
|
||||
```bash
|
||||
# Add newline at end if missing
|
||||
find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \;
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Git Workflow
|
||||
|
||||
1. **Edit**: Make changes to MDC files
|
||||
2. **Stage**: `git add .cursor/rules/filename.mdc`
|
||||
3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix`
|
||||
4. **Commit**: Changes are committed with perfect formatting
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. **Create/Edit**: Use templates from `markdown_templates.mdc`
|
||||
2. **Validate**: Run `npm run markdown:check` before committing
|
||||
3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes
|
||||
4. **Review**: Ensure content quality, not just formatting
|
||||
|
||||
## Model Implementation Checklist
|
||||
|
||||
### Before Starting Workflow
|
||||
|
||||
- [ ] **Configuration Review**: Understand markdownlint rules and settings
|
||||
- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working
|
||||
- [ ] **File Scope**: Identify which files need validation or fixing
|
||||
- [ ] **Backup Strategy**: Consider backing up files before bulk operations
|
||||
|
||||
### During Workflow Execution
|
||||
|
||||
- [ ] **Validation First**: Run `npm run markdown:check` to identify issues
|
||||
- [ ] **Issue Analysis**: Review and understand each validation error
|
||||
- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes
|
||||
- [ ] **Manual Review**: Check files that couldn't be auto-fixed
|
||||
|
||||
### After Workflow Completion
|
||||
|
||||
- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check`
|
||||
- [ ] **Quality Review**: Verify formatting meets project standards
|
||||
- [ ] **Documentation Update**: Update any related documentation or guides
|
||||
- [ ] **Team Communication**: Share workflow results and any manual fixes needed
|
||||
|
||||
### Workflow-Specific Requirements
|
||||
|
||||
- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working
|
||||
- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation
|
||||
- [ ] **Team Guidelines**: Confirm all team members understand the workflow
|
||||
- [ ] **Error Resolution**: Document common issues and their solutions
|
||||
|
||||
---
|
||||
|
||||
**See also**:
|
||||
|
||||
- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
|
||||
- `.cursor/rules/docs/markdown_templates.mdc` for document templates
|
||||
|
||||
**Status**: Active workflow and validation
|
||||
**Priority**: Medium
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: markdown_core.mdc, markdown_templates.mdc
|
||||
**Stakeholders**: Development team, Documentation team
|
||||
Reference in New Issue
Block a user