trent_larson/daily-notification-plugin
4
0
Fork 0
Code Issues Pull Requests 2 Projects Releases Wiki Activity

Merge branch 'research/notification-plugin-enhancement'

Browse Source
This commit is contained in:
Matthew Raymer
2025-10-03 06:07:26 +00:00
parent 0eb709aaf0 c69640cbb2
commit 0fc106cd20
282 changed files with 53047 additions and 1741 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
.cursor/rules/docs/documentation.mdc
View File

@@ -1,345 +1,37 @@
# Documentation Generation — Human Competence First
**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Core Documentation Standards
## Overview
This guide establishes **how documentation should be created and maintained**
across all projects, emphasizing **human competence building** and
**collaborative learning** while ensuring technical accuracy and maintainability.
## Core Principles (Human Competence First)
### 1. **Learning Over Information Dumping**
- **Educational value**: Documents must clearly explain system workings
- **Progressive complexity**: Start simple, build to advanced concepts
- **Real-world examples**: Include practical, actionable examples
- **Why it matters**: Understanding the "why" builds deeper competence
### 2. **Collaboration Over Isolation**
- **Team review**: Documentation should invite discussion and iteration
- **Shared ownership**: Multiple perspectives improve quality and accuracy
- **Feedback loops**: Regular review cycles keep content relevant
- **Why it matters**: Collaborative documentation builds team knowledge
### 3. **Maintainability Over Completeness**
- **Small, focused sets**: Prefer depth over breadth
- **Worth preserving**: Content must motivate humans to keep it updated
- **Clear ownership**: Designate maintainers for each document
- **Why it matters**: Maintainable docs stay useful over time
### 4. **Quality Over Quantity**
- **Avoid filler**: No shallow, generic, or AI-generated explanations
- **Clarity first**: Complex concepts explained simply
- **Actionable content**: Readers should know what to do next
- **Why it matters**: Quality content builds trust and competence
## Documentation Standards
### Content Structure
#### Document Header (Required)
```markdown
# Document Title
**Author**: [Name]
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description
**Maintainer**: [Name]
## Overview
Brief description of the document's purpose and scope.
```
#### Section Organization
1. **Overview/Introduction** - Purpose and scope
2. **Current State** - What exists now
3. **Implementation Details** - How things work
4. **Examples** - Real-world usage
5. **Next Steps** - What to do next
6. **References** - Related resources
### Writing Guidelines
#### **For LLMs (Required)**
- **Always start with purpose**: Why does this document exist?
- **Include learning objectives**: What will readers understand after reading?
- **Provide examples**: Show, don't just tell
- **End with action**: What should readers do next?
#### **For Human Writers**
- **Write for your future self**: Will you understand this in 6 months?
- **Consider skill levels**: Different readers have different needs
- **Include context**: Why does this matter for the project?
- **Invite feedback**: How can this be improved?
## Documentation Types
### 1. **Technical Guides**
- **Purpose**: Explain how systems work
- **Audience**: Developers, engineers, technical users
- **Focus**: Implementation details, APIs, configurations
- **Examples**: Code snippets, configuration files, diagrams
### 2. **Process Documentation**
- **Purpose**: Explain how to accomplish tasks
- **Audience**: Team members, stakeholders
- **Focus**: Step-by-step procedures, workflows
- **Examples**: Checklists, flowcharts, decision trees
### 3. **Architecture Documents**
- **Purpose**: Explain system design and structure
- **Audience**: Architects, developers, stakeholders
- **Focus**: High-level design, trade-offs, decisions
- **Examples**: System diagrams, ADRs, design patterns
### 4. **User Guides**
- **Purpose**: Help users accomplish goals
- **Audience**: End users, customers
- **Focus**: User workflows, features, troubleshooting
- **Examples**: Screenshots, step-by-step instructions
## Quality Assurance
### **Before Publishing Documentation**
- [ ] **Purpose clear**: Why does this document exist?
- [ ] **Audience defined**: Who is this written for?
- [ ] **Examples included**: Are there practical examples?
- [ ] **Actionable**: Do readers know what to do next?
- [ ] **Maintainable**: Is it easy to keep updated?
- [ ] **Collaborative**: Does it invite team input?
### **After Publishing Documentation**
- [ ] **Feedback collected**: Have team members reviewed it?
- [ ] **Usage tracked**: Are people actually using it?
- [ ] **Updates planned**: When will it be reviewed next?
- [ ] **Ownership clear**: Who maintains this document?
## Implementation Examples
### Good Documentation Example
```markdown
# User Authentication System
**Author**: Matthew Raymer
**Date**: 2025-08-17
**Status**: 🎯 **ACTIVE** - Production System
**Maintainer**: Security Team
## Overview
This document explains how user authentication works in our system,
including login flows, security measures, and troubleshooting steps.
## Learning Objectives
After reading this document, you will understand:
- How users log in and authenticate
- What security measures protect user accounts
- How to troubleshoot common authentication issues
- When to escalate security concerns
## Current Implementation
### Login Flow
1. User enters credentials
2. System validates against database
3. JWT token generated and returned
4. Token stored in secure cookie
### Security Measures
- Password hashing with bcrypt
- Rate limiting on login attempts
- JWT expiration after 24 hours
- HTTPS enforcement for all auth requests
## Examples
### Login Request
```json
POST /api/auth/login
{
"email": "user@example.com",
"password": "securepassword123"
}
```
### Successful Response
```json
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires": "2025-08-18T12:00:00Z"
}
```
## Troubleshooting
### Common Issues
- **Invalid credentials**: Check email/password combination
- **Token expired**: User needs to log in again
- **Rate limited**: Wait 15 minutes before retrying
### Escalation Path
1. Check system logs for errors
2. Verify database connectivity
3. Contact security team if suspicious activity
## Next Steps
1. **Test the system**: Try logging in with test credentials
2. **Review security**: Ensure your implementation follows these patterns
3. **Document issues**: Add new troubleshooting steps as you discover them
## References
- [JWT Documentation](https://jwt.io/)
- [Security Best Practices](./security-guide.md)
- [API Reference](./api-docs.md)
---
**Last Updated**: 2025-08-17
**Next Review**: 2025-09-17
**Stakeholders**: Development Team, Security Team, Product Team
### Bad Documentation Example
```markdown
# Authentication
This document describes the authentication system.
## Overview
The system has authentication.
## Implementation
Users can log in.
## Conclusion
That's how authentication works.
```
## Collaboration Points
### **Code Reviews**
- Include documentation updates in code review process
- Ensure new features have corresponding documentation
- Validate that examples match actual implementation
### **Team Reviews**
- Schedule regular documentation review sessions
- Invite different team members to review content
- Collect feedback on clarity and usefulness
### **User Testing**
- Have actual users try to follow documentation
- Observe where they get stuck or confused
- Update content based on real usage patterns
## Maintenance Schedule
### **Weekly**
- Review documentation usage metrics
- Collect feedback from team members
- Plan updates for outdated content
### **Monthly**
- Full review of high-priority documents
- Update examples and screenshots
- Validate links and references
### **Quarterly**
- Comprehensive review of all documentation
- Identify gaps and opportunities
- Plan major documentation projects
## Success Metrics
### **Usage Metrics**
- **Document views**: How often is content accessed?
- **Time on page**: How long do readers spend?
- **Search queries**: What are people looking for?
### **Quality Metrics**
- **Feedback scores**: How do readers rate content?
- **Update frequency**: How often is content refreshed?
- **Maintainer satisfaction**: Are maintainers happy with their docs?
### **Competence Metrics**
- **Question reduction**: Fewer basic questions from team?
- **Implementation speed**: Faster feature development?
- **Knowledge transfer**: Better onboarding for new team members?
## Tools and Resources
### **Documentation Platforms**
- **Markdown**: Standard format for technical documentation
- **GitBook**: Collaborative documentation hosting
- **Notion**: Team knowledge management
- **Confluence**: Enterprise documentation platform
### **Quality Tools**
- **Markdown linting**: Ensure consistent formatting
- **Link checking**: Validate references and links
- **Spell checking**: Maintain professional appearance
- **Accessibility**: Ensure content is usable by all
### **Collaboration Tools**
- **Version control**: Track changes and history
- **Review systems**: Collect feedback and approvals
- **Analytics**: Understand usage patterns
- **Notifications**: Keep team informed of updates
## Implementation Next Steps
1. **Review existing documentation**: Apply these principles to current docs
2. **Identify gaps**: What documentation is missing or outdated?
3. **Plan improvements**: Prioritize documentation updates
4. **Establish processes**: Set up regular review and update cycles
alwaysApply: false
---
# Directive for Documentation Generation
**Last Updated**: 2025-08-17
**Version**: 2.0
**Maintainer**: Matthew Raymer
**Stakeholders**: All Teams
**Next Review**: 2025-09-17
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.
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.
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

96
.cursor/rules/docs/documentation_references_model_agents.mdc Normal file
View File

@@ -0,0 +1,96 @@
---
title: Documentation, References, and Model Agent Use
version: 1.1
alwaysApply: true
scope: code, project-plans
---
# Directive on Documentation, References, and Model Agent Use in Code and Project Plans
To ensure clarity, efficiency, and high-value documentation within code and project plans—and to leverage **model agents** (AI- or automation-based assistants) effectively—contributors must follow these rules:
---
## 1. Documentation and References Must Add Clear Value
- Only include documentation, comments, or reference links when they provide _new, meaningful information_ that assists understanding or decision-making.
- Avoid duplicating content already obvious in the codebase, version history, or linked project documents.
---
## 2. Eliminate Redundant or Noisy References
- Remove references that serve no purpose beyond filling space.
- Model agents may automatically flag and suggest removal of trivial references (e.g., links to unchanged boilerplate or self-evident context).
---
## 3. Explicit Role of Model Agents
Model agents are **active participants** in documentation quality control. Their tasks include:
- **Relevance Evaluation**: Automatically analyze references for their substantive contribution before inclusion.
- **Redundancy Detection**: Flag duplicate or trivial references across commits, files, or tasks.
- **Context Linking**: Suggest appropriate higher-level docs (designs, ADRs, meeting notes) when a code change touches multi-stage or cross-team items.
- **Placement Optimization**: Recommend centralization of references (e.g., in plan overviews, ADRs, or merge commit messages) rather than scattered low-value inline references.
- **Consistency Monitoring**: Ensure references align with team standards (e.g., ADR template, architecture repo, or external policy documents).
Contributors must treat agent recommendations as **first-pass reviews** but remain accountable for final human judgment.
---
## 4. Contextual References for Complex Items
- Use **centralized references** for multi-stage features (e.g., architectural docs, research threads).
- Keep inline code comments light; push broader context into centralized documents.
- Model agents may auto-summarize complex chains of discussion and attach them as a single reference point.
---
## 5. Centralization of Broader Context
- Store overarching context (design docs, proposals, workflows) in accessible, well-indexed places.
- Model agents should assist by **generating reference maps** that track where docs are cited across the codebase.
---
## 6. Focused Documentation
- Documentation should explain **why** and **how** decisions are made, not just what was changed.
- Model agents can auto-generate first-pass explanations from commit metadata, diffs, and linked issues—but humans must refine them for accuracy and intent.
---
## 7. Review and Accountability
- Reviewers and team leads must reject submissions containing unnecessary or low-quality documentation.
- Model agent outputs are aids, not replacements—contributors remain responsible for **final clarity and relevance**.
---
## 8. Continuous Improvement and Agent Feedback Loops
- Encourage iterative development of model agents so their evaluations become more precise over time.
- Contributions should include **feedback on agent suggestions** (e.g., accepted, rejected, or corrected) to train better future outputs.
- Agents should log patterns of “rejected” suggestions for refinement.
---
## 9. Workflow Overview (Mermaid Diagram)
```mermaid
flowchart TD
A[Contributor] -->|Writes Code & Draft Docs| B[Model Agent]
B -->|Evaluates References| C{Relevant?}
C -->|Yes| D[Suggest Placement & Context Links]
C -->|No| E[Flag Redundancy / Noise]
D --> F[Contributor Refines Docs]
E --> F
F --> G[Reviewer]
G -->|Approves / Requests Revisions| H[Final Documentation]
G -->|Feedback on Agent Suggestions| B
```
---
✅ **Outcome:** By integrating disciplined contributor standards with **model agent augmentation**, the team achieves documentation that is consistently _relevant, concise, centralized, and decision-focused_. AI ensures coverage and noise reduction, while humans ensure precision and judgment.

210
.cursor/rules/docs/markdown_core.mdc Normal file
View File

@@ -0,0 +1,210 @@
# 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.
**Primary Focus**: Create educational content that increases human
competence, not just technical descriptions.
## 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
5. **Educational Value**: Focus on increasing reader competence and
understanding
### **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
- ❌ Focus only on technical details without educational context
- ❌ Assume reader has extensive prior knowledge
### **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
- ✅ Explain concepts before implementation details
- ✅ Provide context and motivation for technical choices
- ✅ Include examples that illustrate key concepts
## 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
## Educational Content Standards
### **Content Structure for Learning**
- **Concept First**: Explain what something is before how to use it
- **Context Matters**: Explain why and when to use a feature
- **Progressive Disclosure**: Start simple, add complexity gradually
- **Real Examples**: Use concrete, relatable scenarios
- **Common Questions**: Anticipate and answer reader questions
### **Writing for Understanding**
- **Conversational Tone**: Write as if explaining to a colleague
- **Active Voice**: "You can do this" not "This can be done"
- **Question Format**: "What happens when..." to engage thinking
- **Analogies**: Use familiar concepts to explain complex ideas
- **Limitations**: Clearly state what solutions don't do
## 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
- [ ] **Educational Focus**: Plan content structure for learning progression
- [ ] **Audience Consideration**: Identify target reader knowledge level
### 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
- [ ] **Educational Review**: Verify content increases reader competence
- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly
### 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
- [ ] **Educational Value**: Content increases reader understanding and competence
- [ ] **Context Clarity**: Reader understands when and why to use the information
---
**See also**:
- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
- `.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

314
.cursor/rules/docs/markdown_templates.mdc Normal file
View File

@@ -0,0 +1,314 @@
# Markdown Templates & Examples
> **Agent role**: Reference this file for document templates, structure,
> and examples when creating new documentation.
>
> **Focus**: Create educational content that increases human competence,
> not just technical descriptions.
## 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.
**Educational Goal**: What will the reader learn and how will it increase
their competence?
## Current State
Description of current situation or problem.
**Why This Matters**: Explain the business value and user benefit of
addressing this situation.
## Implementation Plan
### Phase 1: Foundation
- [ ] Task 1
- [ ] Task 2
**Learning Context**: What concepts should the reader understand before
proceeding with implementation?
## Next Steps
1. **Review and approve plan**
2. **Begin implementation**
3. **Test and validate**
**Continued Learning**: Where can the reader go next to deepen their
understanding?
---
**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.
**Business Context**: Why is this specification needed and what problem
does it solve for users?
## Requirements
### Functional Requirements
- [ ] Requirement 1
- [ ] Requirement 2
### Non-Functional Requirements
- [ ] Performance requirement
- [ ] Security requirement
## Technical Design
### Architecture
Description of the technical architecture.
**Design Rationale**: Why was this architecture chosen over alternatives?
What are the trade-offs and benefits?
### 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
**Learning from Testing**: What insights does testing provide about the
system's behavior and design?
---
## Educational Documentation Template
### **Concept Explanation Template**
```markdown
## What is [Concept Name]?
Brief, clear definition of the concept.
## Why Does [Concept Name] Matter?
Explain the business value and user benefit.
## How Does [Concept Name] Work?
High-level explanation of the mechanism.
## When Would You Use [Concept Name]?
Real-world scenarios and use cases.
## Common Misconceptions
Address typical misunderstandings.
## Examples
Concrete examples that illustrate the concept.
## Next Steps
Where to learn more about related concepts.
```
### **Tutorial Template**
```markdown
## Learning Objective
What the reader will accomplish by the end.
## Prerequisites
What the reader should know before starting.
## Step-by-Step Guide
1. **Step 1**: What to do and why
2. **Step 2**: What to do and why
3. **Step 3**: What to do and why
## Verification
How to confirm the tutorial was successful.
## Troubleshooting
Common issues and how to resolve them.
## What You've Learned
Summary of key concepts and skills.
## Next Steps
Where to apply this knowledge next.
```
- [ ] 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/meta_documentation.mdc` for comprehensive documentation workflow
- `.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
View 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