Improve developer experience with shared tooling, cleaner docs.

[ksylvan]

Improve developer experience with shared tooling, cleaner docs.

Summary

This PR updates the VSCode configuration for the BMAD (Breakthrough Method of AI ) agent project by removing the .vscode/ directory from .gitignore and adding standardized VSCode settings and extension recommendations. Additionally, minor formatting improvements were made to various markdown files throughout the project.

Files Changed

.gitignore

• Change: Removed .vscode/ from the ignore list
• Reason: To enable sharing of standardized VSCode settings and extension recommendations across the development team

.vscode/extensions.json (Added)

• Change: Added new file with recommended VSCode extensions
• Reason: Ensures all team members have consistent tooling for markdown linting and spell checking

.vscode/settings.json (Added)

• Change: Added new file with project-specific spell checker dictionary
• Reason: Prevents false positives for domain-specific terminology used throughout the BMAD project

Multiple Markdown Files

• Change: Minor formatting improvements (trailing whitespace removal, consistent heading formatting)
• Files affected:
  • bmad-agent/checklists/*.md
  • bmad-agent/personas/*.md
  • bmad-agent/tasks/*.md
• Reason: Improves consistency and adherence to markdown best practices

Code Changes

VSCode Extension Recommendations

{
        "recommendations": [
                "davidanson.vscode-markdownlint",
                "streetsidesoftware.code-spell-checker"
        ]
}

These extensions will help maintain consistent markdown formatting and catch spelling errors.

Custom Dictionary for Spell Checker

{
        "cSpell.words": [
                "agentic",
                "Axios",
                "BMAD",
                // ... (38 domain-specific terms)
        ]
}

The custom dictionary includes technical terms, framework names, and BMAD-specific terminology to reduce noise in spell checking.

Markdown Formatting

• Removed trailing whitespace from line endings
• Added blank lines after headings for better readability
• Fixed inconsistent formatting in lists and code blocks

Reason for Changes

1. Team Consistency: Sharing VSCode settings ensures all developers have the same development experience and tooling
2. Code Quality: Markdown linting helps maintain consistent documentation formatting
3. Developer Experience: Custom spell checker dictionary reduces false positives and improves productivity
4. Documentation Standards: Formatting improvements make the documentation more professional and easier to read

Impact of Changes

• Positive: Improved developer experience with standardized tooling and reduced spell-check noise
• Positive: Better documentation consistency across the project
• Minimal Risk: Changes are purely development environment configuration and formatting - no functional code changes
• No Breaking Changes: Existing functionality remains unchanged

Test Plan

1. Open the project in VSCode and verify extension recommendations appear
2. Confirm spell checker recognizes custom dictionary terms
3. Run markdown linter to ensure all files pass formatting checks
4. Verify no functional changes to the application behavior

Additional Notes

• The VSCode settings are optional - developers can still use their preferred editors
• The custom dictionary can be expanded as new domain-specific terms are introduced
• Consider adding a pre-commit hook to enforce markdown formatting in the future

[ksylvan]

@bmadcode Brian, I know this might conflict with your template PR #163

However, I wanted to share my VSCode extension recommendations and encourage running markdownlint on all the documentation.

I heartily recommend the two extensions I added to workspace recommendations.

[bmadcode]

Looks good @ksylvan - I can always update my PR. If you can, can you please also let me know what you think of the idea for the template / more generic doc runner if you dont mind also. Im on the fence about embedding instructions into the templates. I think its a good idea, but not sure if its the best way - alternative idea I have is template remains clean, but every template has a metadata section with the instructions for the file.

[ksylvan]

@bmadcode Regarding the templates and embedding instructions:

The cleaner and more modular you make the templates, the more customizable and general/universal they are.

I'll look at the PR more carefully and give you my opinion.

[github-actions]

🎉 This PR is included in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀