From 104fc82820becacb549b924cdce496135dedf983 Mon Sep 17 00:00:00 2001 From: Giovani Moutinho Date: Sun, 15 Jun 2025 18:26:50 -0300 Subject: [PATCH] feat: add multiple RFC template variants - Add minimal template for quick proposals (~12 lines) - Add standard template for structured analysis (~80 lines) - Add detailed template for comprehensive lifecycle (~300 lines) - Update RFC rule to support template configuration - Update configuration to support RFC template selection - Add documentation for RFC template customization --- .cursor-init.example.yaml | 12 +- .../cursor-init/diagrams/gen-er-diagram.mdc | 10 +- .../templates/rfc/rfc_template_detailed.md | 293 ++++++++++++++++ .cursor/templates/rfc/rfc_template_minimal.md | 16 + .../templates/rfc/rfc_template_standard.md | 91 +++++ docs/development/template-customization.md | 313 +++--------------- 6 files changed, 470 insertions(+), 265 deletions(-) diff --git a/.cursor-init.example.yaml b/.cursor-init.example.yaml index 7a3a497..ca649b7 100644 --- a/.cursor-init.example.yaml +++ b/.cursor-init.example.yaml @@ -10,7 +10,17 @@ templates: architecture: "google_style" # Options: google_style, enterprise, arc42 # Onboarding guide templates - onboarding: "general" # Options: general, python, frontend + onboarding: "developer" # Options: developer, contributor, user + + # ===================================================== + # RFC (Request For Comments) Documentation + # ===================================================== + # Options: minimal, standard, detailed + # + # - minimal: Simple RFC for quick proposals (~12 lines) + # - standard: Standard RFC with structured analysis (~80 lines) + # - detailed: Comprehensive RFC with full lifecycle (~300 lines) + rfc: "standard" # Custom template paths - add your own templates custom_template_paths: diff --git a/.cursor/rules/cursor-init/diagrams/gen-er-diagram.mdc b/.cursor/rules/cursor-init/diagrams/gen-er-diagram.mdc index 093e448..6c7ba39 100644 --- a/.cursor/rules/cursor-init/diagrams/gen-er-diagram.mdc +++ b/.cursor/rules/cursor-init/diagrams/gen-er-diagram.mdc @@ -14,11 +14,15 @@ alwaysApply: true - Primary key relationships - Foreign key relationships between tables - 3. **Generating Mermaid ER Diagram:** Based on the extracted schema information, I will create a valid Mermaid `erDiagram` with proper syntax for entities, attributes, and relationships. + 3. **Check Template Configuration:** I will read `.cursor-init.yaml` to determine which data model template variant to use: + - `simple` (default) - Basic ER diagram with entity overview + - `comprehensive` - Detailed data model with full database documentation - 4. **Storing the Diagram:** The generated diagram will be saved to `docs/data-model.md`, creating the file if it doesn't exist or overwriting it if it does. + 4. **Generating Mermaid ER Diagram:** Based on the extracted schema information, I will create a valid Mermaid `erDiagram` with proper syntax for entities, attributes, and relationships. + + 5. **Storing the Diagram:** The generated diagram will be saved to `docs/data-model.md` using the configured data model template variant, creating the file if it doesn't exist or overwriting it if it does. Let me start by searching for SQLAlchemy models in your project..." - I will use the `codebase_search` and `grep_search` tools to find SQLAlchemy models, then use `edit_file` to create the ER diagram documentation. + I will use the `codebase_search` and `grep_search` tools to find SQLAlchemy models, then use `read_file` to check template configuration, and `edit_file` to create the ER diagram documentation using the appropriate template variant. } \ No newline at end of file diff --git a/.cursor/templates/rfc/rfc_template_detailed.md b/.cursor/templates/rfc/rfc_template_detailed.md index e69de29..b5ddac8 100644 --- a/.cursor/templates/rfc/rfc_template_detailed.md +++ b/.cursor/templates/rfc/rfc_template_detailed.md @@ -0,0 +1,293 @@ +# RFC {{RFC_NUMBER}}: {{RFC_TITLE}} + +| Field | Value | +|-------|-------| +| **Author(s)** | {{AUTHOR}} | +| **Status** | {{STATUS}} | +| **Date** | {{DATE}} | +| **Version** | {{VERSION}} | +| **Reviewers** | {{REVIEWERS}} | +| **Implementation Due** | {{DUE_DATE}} | + +## Abstract + +{{ABSTRACT}} + +## Motivation + +### Problem Statement + +{{PROBLEM_STATEMENT}} + +### Goals + +{{GOALS}} + +### Non-Goals + +{{NON_GOALS}} + +### Success Criteria + +{{SUCCESS_CRITERIA}} + +## Background + +### Current State + +{{CURRENT_STATE}} + +### Historical Context + +{{HISTORICAL_CONTEXT}} + +### Related Work + +{{RELATED_WORK}} + +## Detailed Design + +### Overview + +{{DESIGN_OVERVIEW}} + +### System Architecture + +{{SYSTEM_ARCHITECTURE}} + +### API Design + +{{API_DESIGN}} + +### Data Model + +{{DATA_MODEL}} + +### Security Considerations + +{{SECURITY_CONSIDERATIONS}} + +### Performance Implications + +{{PERFORMANCE_IMPLICATIONS}} + +### Compatibility + +{{COMPATIBILITY}} + +## Implementation Plan + +### Phase 1: {{PHASE_1}} + +{{PHASE_1_DETAILS}} + +**Timeline:** {{PHASE_1_TIMELINE}} +**Deliverables:** {{PHASE_1_DELIVERABLES}} + +### Phase 2: {{PHASE_2}} + +{{PHASE_2_DETAILS}} + +**Timeline:** {{PHASE_2_TIMELINE}} +**Deliverables:** {{PHASE_2_DELIVERABLES}} + +### Phase 3: {{PHASE_3}} + +{{PHASE_3_DETAILS}} + +**Timeline:** {{PHASE_3_TIMELINE}} +**Deliverables:** {{PHASE_3_DELIVERABLES}} + +## Alternatives Considered + +### Alternative 1: {{ALT_1_NAME}} + +{{ALT_1_DESCRIPTION}} + +**Advantages:** + +- {{ALT_1_ADVANTAGE_1}} +- {{ALT_1_ADVANTAGE_2}} + +**Disadvantages:** + +- {{ALT_1_DISADVANTAGE_1}} +- {{ALT_1_DISADVANTAGE_2}} + +**Decision:** {{ALT_1_DECISION}} + +### Alternative 2: {{ALT_2_NAME}} + +{{ALT_2_DESCRIPTION}} + +**Advantages:** + +- {{ALT_2_ADVANTAGE_1}} +- {{ALT_2_ADVANTAGE_2}} + +**Disadvantages:** + +- {{ALT_2_DISADVANTAGE_1}} +- {{ALT_2_DISADVANTAGE_2}} + +**Decision:** {{ALT_2_DECISION}} + +### Alternative 3: {{ALT_3_NAME}} + +{{ALT_3_DESCRIPTION}} + +**Advantages:** + +- {{ALT_3_ADVANTAGE_1}} +- {{ALT_3_ADVANTAGE_2}} + +**Disadvantages:** + +- {{ALT_3_DISADVANTAGE_1}} +- {{ALT_3_DISADVANTAGE_2}} + +**Decision:** {{ALT_3_DECISION}} + +## Risk Assessment + +| Risk | Probability | Impact | Mitigation Strategy | +|------|-------------|--------|-------------------| +| {{RISK_1}} | {{PROB_1}} | {{IMPACT_1}} | {{MITIGATION_1}} | +| {{RISK_2}} | {{PROB_2}} | {{IMPACT_2}} | {{MITIGATION_2}} | +| {{RISK_3}} | {{PROB_3}} | {{IMPACT_3}} | {{MITIGATION_3}} | +| {{RISK_4}} | {{PROB_4}} | {{IMPACT_4}} | {{MITIGATION_4}} | + +## Resource Requirements + +### Team Requirements + +{{TEAM_REQUIREMENTS}} + +### Infrastructure Requirements + +{{INFRASTRUCTURE_REQUIREMENTS}} + +### Budget Considerations + +{{BUDGET_CONSIDERATIONS}} + +### Timeline + +{{PROJECT_TIMELINE}} + +## Measurement and Evaluation + +### Key Performance Indicators + +{{KPIS}} + +### Monitoring Strategy + +{{MONITORING_STRATEGY}} + +### Success Metrics + +{{SUCCESS_METRICS}} + +### Failure Criteria + +{{FAILURE_CRITERIA}} + +## Dependencies + +### Internal Dependencies + +{{INTERNAL_DEPENDENCIES}} + +### External Dependencies + +{{EXTERNAL_DEPENDENCIES}} + +### Blocking Issues + +{{BLOCKING_ISSUES}} + +## Testing Strategy + +### Unit Testing + +{{UNIT_TESTING}} + +### Integration Testing + +{{INTEGRATION_TESTING}} + +### Performance Testing + +{{PERFORMANCE_TESTING}} + +### Security Testing + +{{SECURITY_TESTING}} + +## Rollout Plan + +### Deployment Strategy + +{{DEPLOYMENT_STRATEGY}} + +### Rollback Plan + +{{ROLLBACK_PLAN}} + +### Communication Plan + +{{COMMUNICATION_PLAN}} + +### Training Requirements + +{{TRAINING_REQUIREMENTS}} + +## Future Considerations + +### Scalability + +{{SCALABILITY_CONSIDERATIONS}} + +### Evolution Path + +{{EVOLUTION_PATH}} + +### Deprecation Strategy + +{{DEPRECATION_STRATEGY}} + +## Open Questions + +{{OPEN_QUESTIONS}} + +## References + +{{REFERENCES}} + +## Appendices + +### Appendix A: {{APPENDIX_A_TITLE}} + +{{APPENDIX_A_CONTENT}} + +### Appendix B: {{APPENDIX_B_TITLE}} + +{{APPENDIX_B_CONTENT}} + +--- + +## Review History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| {{VERSION_1}} | {{DATE_1}} | {{AUTHOR_1}} | {{CHANGES_1}} | +| {{VERSION_2}} | {{DATE_2}} | {{AUTHOR_2}} | {{CHANGES_2}} | + +## Approval + +| Role | Name | Date | Signature | +|------|------|------|-----------| +| **Technical Lead** | {{TECH_LEAD}} | {{TECH_LEAD_DATE}} | {{TECH_LEAD_SIG}} | +| **Product Owner** | {{PRODUCT_OWNER}} | {{PO_DATE}} | {{PO_SIG}} | +| **Architecture Review** | {{ARCH_REVIEWER}} | {{ARCH_DATE}} | {{ARCH_SIG}} | diff --git a/.cursor/templates/rfc/rfc_template_minimal.md b/.cursor/templates/rfc/rfc_template_minimal.md index e69de29..a20f893 100644 --- a/.cursor/templates/rfc/rfc_template_minimal.md +++ b/.cursor/templates/rfc/rfc_template_minimal.md @@ -0,0 +1,16 @@ +# RFC: {{RFC_TITLE}} + +**Author:** {{AUTHOR}} +**Date:** {{DATE}} + +## Problem + +{{PROBLEM}} + +## Proposed Solution + +{{SOLUTION}} + +## Discussion + +{{DISCUSSION}} diff --git a/.cursor/templates/rfc/rfc_template_standard.md b/.cursor/templates/rfc/rfc_template_standard.md index e69de29..b29d23a 100644 --- a/.cursor/templates/rfc/rfc_template_standard.md +++ b/.cursor/templates/rfc/rfc_template_standard.md @@ -0,0 +1,91 @@ +# RFC: {{RFC_TITLE}} + +**Date:** {{DATE}} +**Author:** {{AUTHOR}} +**Status:** {{STATUS}} + +## Summary + +{{SUMMARY}} + +## Problem Statement + +{{PROBLEM_STATEMENT}} + +## Proposed Solution + +{{PROPOSED_SOLUTION}} + +## Implementation Details + +{{IMPLEMENTATION_DETAILS}} + +### Technical Approach + +{{TECHNICAL_APPROACH}} + +### Timeline + +{{TIMELINE}} + +### Resource Requirements + +{{RESOURCE_REQUIREMENTS}} + +## Alternatives Considered + +### Alternative 1: {{ALTERNATIVE_1}} + +{{ALTERNATIVE_1_DESCRIPTION}} + +**Pros:** + +- {{ALTERNATIVE_1_PRO_1}} +- {{ALTERNATIVE_1_PRO_2}} + +**Cons:** + +- {{ALTERNATIVE_1_CON_1}} +- {{ALTERNATIVE_1_CON_2}} + +### Alternative 2: {{ALTERNATIVE_2}} + +{{ALTERNATIVE_2_DESCRIPTION}} + +**Pros:** + +- {{ALTERNATIVE_2_PRO_1}} +- {{ALTERNATIVE_2_PRO_2}} + +**Cons:** + +- {{ALTERNATIVE_2_CON_1}} +- {{ALTERNATIVE_2_CON_2}} + +## Risks and Mitigation + +| Risk | Impact | Mitigation | +|------|--------|------------| +| {{RISK_1}} | {{IMPACT_1}} | {{MITIGATION_1}} | +| {{RISK_2}} | {{IMPACT_2}} | {{MITIGATION_2}} | +| {{RISK_3}} | {{IMPACT_3}} | {{MITIGATION_3}} | + +## Success Metrics + +{{SUCCESS_METRICS}} + +## Dependencies + +{{DEPENDENCIES}} + +## Open Questions + +{{OPEN_QUESTIONS}} + +## Discussion + +{{DISCUSSION}} + +## Appendix + +{{APPENDIX}} diff --git a/docs/development/template-customization.md b/docs/development/template-customization.md index 4f2b876..84a5ece 100644 --- a/docs/development/template-customization.md +++ b/docs/development/template-customization.md @@ -1,296 +1,87 @@ -### Template Customization Guide +# Template Customization Guide -This guide explains how to customize documentation templates used by cursor-init slash commands. +The cursor-init framework provides multiple template variants for RFC (Request For Comments) documentation, allowing you to customize the documentation style to match your project's needs. -## Overview - -cursor-init supports multiple template variants for different documentation types, allowing you to choose the style that best fits your team's needs. Templates can be configured globally via `.cursor-init.yaml` or selected per command. - -## Available Template Types - -### Architecture Decision Records (ADRs) - -The `/adr` command supports four template variants: - -#### 1. Nygard Style (Default) - -**Template:** `adr_template_nygard.md` -**Best for:** Classic Michael Nygard style ADRs -**Sections:** Context, Decision, Consequences - -```yaml -templates: - adr: "nygard_style" -``` - -#### 2. Full Template - -**Template:** `adr_template_full.md` -**Best for:** Complex architectural decisions requiring thorough analysis -**Sections:** Problem Statement, Context, Assumptions, Options Analysis, Implementation Plan, Success Metrics, Risk Assessment - -```yaml -templates: - adr: "full" -``` - -#### 3. Lightweight Template - -**Template:** `adr_template_lightweight.md` -**Best for:** Simple decisions that don't require extensive documentation -**Sections:** Problem, Decision, Alternatives, Consequences - -```yaml -templates: - adr: "lightweight" -``` - -#### 4. MADR Template +## Configuration -**Template:** `adr_template_madr.md` -**Best for:** Teams following MADR (Markdown ADR) conventions -**Sections:** Context and Problem Statement, Decision Drivers, Considered Options, Decision Outcome, Pros/Cons Analysis +Create a `.cursor-init.yaml` file in your project root to configure template variants: ```yaml templates: - adr: "madr" + # RFC Templates + rfc: "standard" # Options: minimal, standard, detailed ``` -## Configuration - -### Global Configuration - -Create a `.cursor-init.yaml` file in your project root to set default templates: - -```yaml -# Template preferences - choose your preferred style for each document type -templates: - # ADR (Architecture Decision Record) templates - adr: "nygard_style" # Options: nygard_style, full, lightweight, madr +## RFC Templates - # Architecture documentation templates - architecture: "google_style" # Options: google_style, enterprise, arc42 +### `minimal` - # Onboarding guide templates - onboarding: "general" # Options: general, python, frontend +- **Description**: Simple RFC for quick proposals +- **Best For**: Informal proposals or brainstorming +- **Length**: ~12 lines +- **Sections**: Problem, Proposed Solution, Discussion -# Custom template paths - add your own templates -custom_template_paths: - # Example: Add a custom security ADR template - - name: "security_adr" - path: ".cursor/templates/custom/security-adr.md" -``` +### `standard` (Default) -### Per-Command Selection +- **Description**: Standard RFC with structured analysis +- **Best For**: Most RFC scenarios requiring structured evaluation +- **Length**: ~80 lines +- **Sections**: Summary, Problem Statement, Proposed Solution, Implementation Details, Alternatives, Risks, Success Metrics -Some commands allow you to specify the template variant directly: +### `detailed` -```bash -# CLI examples (when available) -cursor-init adr --template=full "Choose database technology" -cursor-init adr --template=lightweight "Update logging format" -``` +- **Description**: Comprehensive RFC with full lifecycle management +- **Best For**: Complex proposals requiring formal approval process +- **Length**: ~300 lines +- **Sections**: Abstract, Motivation, Background, Detailed Design, Implementation Plan, Alternatives, Risk Assessment, Resource Requirements, Testing Strategy, Rollout Plan, Approval Process ## Template Structure -### Placeholder System - All templates use a consistent placeholder system: -- `{{ADR_NUMBER}}` - Auto-numbered sequentially (0001, 0002, etc.) -- `{{ADR_TITLE}}` - Sanitized from user input -- `{{CONTEXT}}` - Pre-filled from codebase search -- `{{DATE}}` - Current date in ISO format -- `{{AUTHORS}}` - Project contributors (when available) -- `{{STAKEHOLDERS}}` - Key decision stakeholders +### Common Placeholders -### Template Locations +- `{{RFC_TITLE}}` - RFC title +- `{{DATE}}` - Current date +- `{{AUTHOR}}` - Document author -Default templates are stored in: +### RFC-Specific Placeholders -``` -.cursor/templates/ -├── adr/ -│ ├── adr_template_nygard.md -│ ├── adr_template_full.md -│ ├── adr_template_lightweight.md -│ └── adr_template_madr.md -├── architecture/ -│ └── ... -└── onboarding/ - └── ... -``` +- `{{RFC_NUMBER}}` - RFC number (detailed template) +- `{{STATUS}}` - RFC status +- `{{PROBLEM_STATEMENT}}` - Problem description +- `{{PROPOSED_SOLUTION}}` - Solution details -## Creating Custom Templates +## Command Integration -### 1. Create Template File +The `/rfc "Title"` command respects RFC template configuration and will use the configured variant when creating new RFCs. -Create your custom template in `.cursor/templates/custom/`: - -```markdown -### {{ADR_NUMBER}}-{{ADR_TITLE}} - -**Status:** Proposed -**Security Level:** {{SECURITY_LEVEL}} -**Compliance:** {{COMPLIANCE_REQUIREMENTS}} - -## Security Context - -{{SECURITY_CONTEXT}} -[Describe security implications and requirements] - -## Threat Analysis - -{{THREAT_ANALYSIS}} -[Identify potential security threats] - -## Decision - -{{DECISION}} -[Security-focused decision with risk mitigation] - -## Security Consequences - -{{SECURITY_CONSEQUENCES}} -[Security implications of this decision] -``` +### Automatic Template Selection -### 2. Register Custom Template - -Add to your `.cursor-init.yaml`: - -```yaml -custom_template_paths: - - name: "security_adr" - path: ".cursor/templates/custom/security-adr.md" -``` - -### 3. Use Custom Template - -Reference in configuration: - -```yaml -templates: - adr: "security_adr" # Use your custom template -``` - -## Template Development Guidelines - -### 1. Placeholder Conventions - -- Use `{{UPPERCASE_WITH_UNDERSCORES}}` for placeholders -- Provide descriptive inline guidance: `[Describe what goes here]` -- Include examples where helpful - -### 2. Section Structure - -- Use consistent markdown heading levels -- Bold important metadata: `**Status:** Proposed` -- Group related information logically - -### 3. Content Guidance - -- Provide clear instructions for each section -- Include examples of good content -- Explain the purpose of each section - -### 4. Template Validation - -Test your templates by: - -1. Creating a test ADR: `/adr "Test Decision"` -2. Checking placeholder replacement works correctly -3. Verifying the generated markdown is well-formatted -4. Ensuring all sections have appropriate guidance - -## Advanced Customization - -### Framework-Specific Templates - -Templates can be customized based on detected frameworks: - -```yaml -templates: - adr: "nygard_style" - -# Override for specific frameworks -framework_overrides: - python_framework: "fastapi" - -# Framework-specific template variants -framework_templates: - fastapi: - adr: "api_focused_adr" -``` - -### Conditional Sections - -Templates can include conditional content: - -```markdown -## API Impact -{{#IF_API_CHANGE}} -{{API_IMPACT}} -[Describe impact on API contracts and versioning] -{{/IF_API_CHANGE}} -``` - -### Template Inheritance - -Extend existing templates: - -```yaml -custom_template_paths: - - name: "enhanced_nygard" - path: ".cursor/templates/custom/enhanced-nygard.md" - extends: "nygard_style" # Inherit from base template -``` - -## Troubleshooting - -### Common Issues - -1. **Template not found**: Check file path and spelling in `.cursor-init.yaml` -2. **Placeholders not replaced**: Ensure proper `{{PLACEHOLDER}}` format -3. **Configuration ignored**: Verify `.cursor-init.yaml` is valid YAML - -### Debug Template Selection - -Use the `/list-templates` command to see available templates and current configuration: - -``` -/list-templates -``` +If no `.cursor-init.yaml` exists, commands use the default template: `standard` -This will show: +## Best Practices -- Available default templates -- Configured custom templates -- Current template preferences -- Template file locations +### Template Selection -## Contributing Templates +- **Start Simple**: Begin with minimal for quick ideas, upgrade to standard/detailed as needed +- **Match Complexity**: Choose template complexity based on proposal scope +- **Team Consistency**: Use same templates across team proposals -To contribute new templates to the project: +### Customization -1. **Create Template**: Follow the guidelines above -2. **Add Documentation**: Update this guide with your template details -3. **Update Configuration**: Add to default options -4. **Test Thoroughly**: Ensure placeholders work correctly -5. **Submit PR**: Include template file, documentation updates, and tests +- **Placeholder Values**: Populate placeholders with meaningful content +- **Section Relevance**: Remove irrelevant sections for your proposal +- **Team Input**: Get team feedback on template choices -### Template Contribution Checklist +## Contributing -- [ ] Template follows placeholder conventions -- [ ] Includes clear section guidance -- [ ] Tested with `/adr` command -- [ ] Documentation updated -- [ ] Configuration files updated -- [ ] Added to available options lists +### Adding New Templates -## Resources +1. Create template file with appropriate placeholders +2. Add to RFC template directory +3. Update configuration options +4. Document template purpose and usage +5. Test with different proposal scenarios -- **Template Examples**: [.cursor/templates/](../.cursor/templates/) -- **Configuration Reference**: [.cursor-init.example.yaml](../.cursor-init.example.yaml) -- **ADR Best Practices**: [adr/0001-record-architecture-decisions.md](../adr/0001-record-architecture-decisions.md) -- **Contributing Guide**: [CONTRIBUTING.md](../../CONTRIBUTING.md) +The cursor-init template system is designed to be flexible and extensible. Choose the templates that best fit your project's documentation needs and customize them as required.