From 6509adc49dee41a152b19de3fdeff1887206f0bc Mon Sep 17 00:00:00 2001 From: Giovani Moutinho Date: Sun, 15 Jun 2025 17:54:48 -0300 Subject: [PATCH] feat: enhance ADR templates with multiple variants and configuration support --- .cursor-init.example.yaml | 2 +- .../rules/cursor-init/documentation/adr.mdc | 43 +-- .cursor/templates/adr/adr_template_full.md | 134 ++++++++ .../templates/adr/adr_template_lightweight.md | 30 ++ .cursor/templates/adr/adr_template_madr.md | 97 ++++++ cli/cursor_init/config.py | 2 +- docs/development/template-customization.md | 296 ++++++++++++++++++ docs/onboarding.md | 14 +- 8 files changed, 591 insertions(+), 27 deletions(-) create mode 100644 .cursor/templates/adr/adr_template_madr.md create mode 100644 docs/development/template-customization.md diff --git a/.cursor-init.example.yaml b/.cursor-init.example.yaml index 2d96213..7a3a497 100644 --- a/.cursor-init.example.yaml +++ b/.cursor-init.example.yaml @@ -4,7 +4,7 @@ # Template preferences - choose your preferred style for each document type templates: # ADR (Architecture Decision Record) templates - adr: "nygard_style" # Options: nygard_style, full, lightweight + adr: "nygard_style" # Options: nygard_style, full, lightweight, madr # Architecture documentation templates architecture: "google_style" # Options: google_style, enterprise, arc42 diff --git a/.cursor/rules/cursor-init/documentation/adr.mdc b/.cursor/rules/cursor-init/documentation/adr.mdc index af9487b..74307d0 100644 --- a/.cursor/rules/cursor-init/documentation/adr.mdc +++ b/.cursor/rules/cursor-init/documentation/adr.mdc @@ -4,32 +4,35 @@ globs: alwaysApply: true --- @if(user_message.starts_with("/adr")) { - "Okay, I will create a new Architecture Decision Record based on your input. + "I will create a new Architecture Decision Record based on your input. - 1. **Extracting and Sanitizing the Title:** I will extract the text after `/adr`. If no text is provided, I will use `untitled-adr` as the default title. I will then sanitize this title to be lowercase and kebab-case for the filename, and also refine it for clarity and conciseness for the document's main title. - 2. **Determining the Next ADR Number:** I will use the `list_dir` tool to list the contents of the `docs/adr/` directory. From the filenames, I will identify the highest existing ADR number and increment it by one. If no ADRs are found, I will start with `0001`. - 3. **Gathering Context:** I will use the `codebase_search` tool with the extracted ADR title to find relevant information from the project's codebase. This context will be used to pre-fill the **Context**, **Decision**, and **Consequences** sections of the ADR. I will prioritize using the `codebase_search` tool for this. - 4. **Generating the ADR Content:** I will populate the new file with the following ADR template. I will replace `[ADR Number]` with the determined sequential number, `[Refined Title]` with the refined title, and insert relevant context from the `codebase_search` results into the **Context** section. + 1. **Extracting and Sanitizing the Title:** I will extract the text after `/adr`. If no text is provided, I will use `untitled-adr` as the default title. I will then sanitize this title to be lowercase and kebab-case for the filename, and also refine it for clarity and conciseness for the document's main title. - ``` - ### [ADR Number]-[Refined Title] + 2. **Determining the Next ADR Number:** I will use the `list_dir` tool to list the contents of the `docs/adr/` directory. From the filenames, I will identify the highest existing ADR number and increment it by one. If no ADRs are found, I will start with `0001`. - **Status:** Proposed + 3. **Template Selection:** I will check for a `.cursor-init.yaml` configuration file to determine which ADR template variant to use. Available options are: + - `nygard_style` (default) - Classic Nygard template with Context, Decision, Consequences + - `full` - Comprehensive template with Problem Statement, Assumptions, Options Analysis, Implementation Plan + - `lightweight` - Minimal template for simple decisions + - `madr` - MADR-style template with Decision Drivers and structured options analysis - **Context:** - [Describe the forces at play, including technological, political, social, and project local.] + 4. **Gathering Context:** I will use the `codebase_search` tool with the extracted ADR title to find relevant information from the project's codebase. This context will be used to pre-fill the appropriate sections of the selected template. - // Relevant codebase context from search results will be inserted here, for example: - // - filepath/to/code: relevant code snippet + 5. **Reading Template:** I will read the selected template file from `.cursor/templates/adr/adr_template_[variant].md` and populate it with: + - `{{ADR_NUMBER}}` - The determined sequential number + - `{{ADR_TITLE}}` - The refined title + - `{{CONTEXT}}` - Relevant codebase context from search results + - `{{DATE}}` - Current date + - Other template-specific placeholders based on the selected variant - **Decision:** - [Describe the decision being made, and why it was chosen over alternatives.] + 6. **Creating the ADR File:** Finally, I will create the new ADR file in the `docs/adr/` directory using the populated template content. The filename will be constructed using the determined ADR number and the sanitized title (e.g., `docs/adr/000X-sanitized-title.md`). - **Consequences:** - [Describe the results of the decision, good or bad.] - ``` - 5. **Creating the File:** Finally, I will create the new ADR file in the `docs/adr/` directory using the `edit_file` tool. The filename will be constructed using the determined ADR number and the sanitized title (e.g., `docs/adr/000X-sanitized-title.md`). + **Template Configuration:** + To customize the ADR template used, create a `.cursor-init.yaml` file in your project root with: + ```yaml + templates: + adr: \"nygard_style\" # Options: nygard_style, full, lightweight, madr + ``` - Please provide a brief title for the ADR after `/adr`. If you provide no title, I will use `untitled-adr` as a default. - " + Please provide a brief title for the ADR after `/adr`. If you provide no title, I will use `untitled-adr` as a default." } \ No newline at end of file diff --git a/.cursor/templates/adr/adr_template_full.md b/.cursor/templates/adr/adr_template_full.md index e69de29..ab15b09 100644 --- a/.cursor/templates/adr/adr_template_full.md +++ b/.cursor/templates/adr/adr_template_full.md @@ -0,0 +1,134 @@ +### {{ADR_NUMBER}}-{{ADR_TITLE}} + +**Status:** Proposed + +**Date:** {{DATE}} + +**Authors:** {{AUTHORS}} + +**Stakeholders:** {{STAKEHOLDERS}} + +## Problem Statement + +{{PROBLEM_STATEMENT}} +[What problem are we trying to solve? What is the current situation that needs to change?] + +## Context + +{{CONTEXT}} +[Describe the forces at play, including technological, political, social, and project local. What are the business requirements and constraints?] + +## Assumptions + +{{ASSUMPTIONS}} +[List any assumptions being made that could affect this decision] + +## Options Considered + +### Option 1: {{OPTION_1_NAME}} + +**Description:** [Brief description of the option] +**Pros:** + +- [List advantages] + +**Cons:** + +- [List disadvantages] + +**Implementation Effort:** [High/Medium/Low] + +### Option 2: {{OPTION_2_NAME}} + +**Description:** [Brief description of the option] +**Pros:** + +- [List advantages] + +**Cons:** + +- [List disadvantages] + +**Implementation Effort:** [High/Medium/Low] + +### Option 3: {{OPTION_3_NAME}} + +**Description:** [Brief description of the option] +**Pros:** + +- [List advantages] + +**Cons:** + +- [List disadvantages] + +**Implementation Effort:** [High/Medium/Low] + +## Decision + +{{DECISION}} +[Describe the chosen solution and explain why it was selected over the alternatives. Include the rationale behind the decision.] + +## Rationale + +{{RATIONALE}} +[Provide detailed reasoning for why this decision was made, including trade-offs considered] + +## Consequences + +### Positive Consequences + +{{POSITIVE_CONSEQUENCES}} + +- [List expected benefits and improvements] + +### Negative Consequences + +{{NEGATIVE_CONSEQUENCES}} + +- [List potential drawbacks or challenges] + +### Neutral Consequences + +{{NEUTRAL_CONSEQUENCES}} + +- [List other impacts that are neither clearly positive nor negative] + +## Implementation Plan + +{{IMPLEMENTATION_PLAN}} +[High-level steps needed to implement this decision] + +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Success Metrics + +{{SUCCESS_METRICS}} +[How will we measure the success of this decision?] + +## Dependencies + +{{DEPENDENCIES}} +[List any dependencies on other ADRs, systems, or external factors] + +## Risks and Mitigation + +{{RISKS_AND_MITIGATION}} +[Identify potential risks and how they will be mitigated] + +## Future Considerations + +{{FUTURE_CONSIDERATIONS}} +[What might we need to revisit in the future? What could change our decision?] + +## Related ADRs + +{{RELATED_ADRS}} +[List any related or superseded ADRs] + +## References + +{{REFERENCES}} +[Include links to relevant documentation, research, or external resources] diff --git a/.cursor/templates/adr/adr_template_lightweight.md b/.cursor/templates/adr/adr_template_lightweight.md index e69de29..89acf39 100644 --- a/.cursor/templates/adr/adr_template_lightweight.md +++ b/.cursor/templates/adr/adr_template_lightweight.md @@ -0,0 +1,30 @@ +### {{ADR_NUMBER}}-{{ADR_TITLE}} + +**Status:** Proposed + +**Date:** {{DATE}} + +## Problem + +{{PROBLEM}} +[What problem are we trying to solve?] + +## Decision + +{{DECISION}} +[What solution did we choose and why?] + +## Alternatives Considered + +{{ALTERNATIVES}} +[What other options were considered? Why were they rejected?] + +## Consequences + +{{CONSEQUENCES}} +[What are the positive and negative outcomes of this decision?] + +## Notes + +{{NOTES}} +[Any additional context, implementation details, or future considerations] diff --git a/.cursor/templates/adr/adr_template_madr.md b/.cursor/templates/adr/adr_template_madr.md new file mode 100644 index 0000000..716b96a --- /dev/null +++ b/.cursor/templates/adr/adr_template_madr.md @@ -0,0 +1,97 @@ +### {{ADR_NUMBER}}-{{ADR_TITLE}} + +- **Status:** Proposed +- **Date:** {{DATE}} +- **Deciders:** {{DECIDERS}} +- **Technical Story:** {{TECHNICAL_STORY}} + +## Context and Problem Statement + +{{CONTEXT_AND_PROBLEM_STATEMENT}} + +[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] + +## Decision Drivers + +{{DECISION_DRIVERS}} + +[List the factors that influence the decision] + +- [driver 1, e.g., a force, facing concern, ...] +- [driver 2, e.g., a force, facing concern, ...] +- [driver 3, e.g., a force, facing concern, ...] + +## Considered Options + +{{CONSIDERED_OPTIONS}} + +[List the options that were considered] + +- [option 1] +- [option 2] +- [option 3] + +## Decision Outcome + +**Chosen option:** {{CHOSEN_OPTION}} + +[Justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force | ... | comes out best (see below).] + +### Positive Consequences + +{{POSITIVE_CONSEQUENCES}} + +- [e.g., improvement of quality attribute satisfaction, follow-up decisions required, ...] +- ... + +### Negative Consequences + +{{NEGATIVE_CONSEQUENCES}} + +- [e.g., compromising quality attribute, follow-up decisions required, ...] +- ... + +## Pros and Cons of the Options + +### {{OPTION_1_NAME}} + +{{OPTION_1_DESCRIPTION}} + +[example | description | pointer to more information | ...] + +- Good, because [argument a] +- Good, because [argument b] +- Bad, because [argument c] +- ... + +### {{OPTION_2_NAME}} + +{{OPTION_2_DESCRIPTION}} + +[example | description | pointer to more information | ...] + +- Good, because [argument a] +- Good, because [argument b] +- Bad, because [argument c] +- ... + +### {{OPTION_3_NAME}} + +{{OPTION_3_DESCRIPTION}} + +[example | description | pointer to more information | ...] + +- Good, because [argument a] +- Good, because [argument b] +- Bad, because [argument c] +- ... + +## Links + +{{LINKS}} + +[Link type] [Link to ADR] +[Link type] [Link to ADR] + +- [Link type] [Link to documentation] +- [Link type] [Link to external resource] diff --git a/cli/cursor_init/config.py b/cli/cursor_init/config.py index 0e7cc33..b8fd294 100644 --- a/cli/cursor_init/config.py +++ b/cli/cursor_init/config.py @@ -33,7 +33,7 @@ def _load_config(self) -> Dict[str, Any]: def _get_default_config(self) -> Dict[str, Any]: return { 'templates': { - 'adr': 'nygard_style', + 'adr': 'nygard_style', # Options: nygard_style, full, lightweight, madr 'architecture': 'google_style', 'onboarding': 'general' }, diff --git a/docs/development/template-customization.md b/docs/development/template-customization.md new file mode 100644 index 0000000..4f2b876 --- /dev/null +++ b/docs/development/template-customization.md @@ -0,0 +1,296 @@ +### Template Customization Guide + +This guide explains how to customize documentation templates used by cursor-init slash commands. + +## 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 + +**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 + +```yaml +templates: + adr: "madr" +``` + +## 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 + + # Architecture documentation templates + architecture: "google_style" # Options: google_style, enterprise, arc42 + + # Onboarding guide templates + onboarding: "general" # Options: general, python, frontend + +# 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" +``` + +### Per-Command Selection + +Some commands allow you to specify the template variant directly: + +```bash +# CLI examples (when available) +cursor-init adr --template=full "Choose database technology" +cursor-init adr --template=lightweight "Update logging format" +``` + +## 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 + +### Template Locations + +Default templates are stored in: + +``` +.cursor/templates/ +├── adr/ +│ ├── adr_template_nygard.md +│ ├── adr_template_full.md +│ ├── adr_template_lightweight.md +│ └── adr_template_madr.md +├── architecture/ +│ └── ... +└── onboarding/ + └── ... +``` + +## Creating Custom Templates + +### 1. Create Template File + +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] +``` + +### 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 +``` + +This will show: + +- Available default templates +- Configured custom templates +- Current template preferences +- Template file locations + +## Contributing Templates + +To contribute new templates to the project: + +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 + +### Template Contribution Checklist + +- [ ] Template follows placeholder conventions +- [ ] Includes clear section guidance +- [ ] Tested with `/adr` command +- [ ] Documentation updated +- [ ] Configuration files updated +- [ ] Added to available options lists + +## Resources + +- **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) diff --git a/docs/onboarding.md b/docs/onboarding.md index 342033c..33d44e0 100644 --- a/docs/onboarding.md +++ b/docs/onboarding.md @@ -105,25 +105,29 @@ This guide provides essential information for contributors to the AI-Cursor-Init ### AI Integration -- Multi-provider support with fallback mechanisms +* Multi-provider support with fallback mechanisms + * Context-aware documentation generation * Intelligent framework detection and content customization ### Template System -- Framework-specific templates (Python/FastAPI, TypeScript/React) +* Framework-specific templates (Python/FastAPI, TypeScript/React) + * Multiple variants per document type -* Custom template support via configuration +* Custom template support via configuration (see [Template Customization Guide](development/template-customization.md)) ### Cursor IDE Integration -- Slash commands for in-IDE documentation workflow +* Slash commands for in-IDE documentation workflow + * Zero-installation setup through Cursor rules * Seamless integration with existing project workflows ### Diagram Generation -- Mermaid-based diagrams stored as version-controlled text +* Mermaid-based diagrams stored as version-controlled text + * ER diagrams from SQLAlchemy model analysis * Architecture diagrams from project structure analysis