05-tasks-pre-commit-cspell.md

Relevant Files

• .cspell.json - New file at repository root containing cspell configuration with project-specific dictionary, file patterns, and exclusions
• .pre-commit-config.yaml - Existing pre-commit configuration file that needs cspell hook added after file format checks but before code linting hooks
• CONTRIBUTING.md - Existing contributing guide that needs spell checking section added

Tasks

• 1.0 Create cspell Configuration File
  • Demo Criteria: File .cspell.json exists at repository root with project-specific dictionary terms (Liatrio, slash-man, SDD, MCP, etc.), dependency names (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.), proper technical term capitalization (GitHub, Python, JSON, YAML, CLI, MCP), markdown file patterns configured, CHANGELOG.md excluded, and code block/URL/file path exclusions configured. Running cspell --config .cspell.json README.md validates configuration works without false positives
  • Proof Artifact(s): Created .cspell.json file at repository root, cspell command output showing configuration loaded successfully (0 issues found), dictionary terms visible in config file (all project-specific, dependency, and technical terms included), JSON validation passed, Pre-commit JSON check passed
  • 1.1 Create .cspell.json file at repository root with basic structure including version, language, files, ignorePaths, words, and flagWords fields
  • 1.2 Configure language field to use ["en"] for English dictionary
  • 1.3 Configure files field to include markdown file patterns: ["**/*.md"]
  • 1.4 Configure ignorePaths field to exclude CHANGELOG.md from spell checking
  • 1.5 Add project-specific terms to words array: "Liatrio", "slash-man", "SDD", "MCP", "spec-driven", "liatrio-labs"
  • 1.6 Add dependency names to words array: "pytest", "ruff", "typer", "fastmcp", "questionary", "uvx", "uv", "pyyaml", "tomli", "hatchling", "semantic-release", "commitlint", "markdownlint"
  • 1.7 Add properly capitalized technical terms to words array: "GitHub", "Python", "JSON", "YAML", "CLI", "MCP", "HTTP", "STDIO", "PyPI", "CI", "CD", "API", "REST"
  • 1.8 Configure flagWords or use regex patterns to exclude common false positives: code blocks (backtick blocks), URLs (http://, https://), file paths (absolute and relative paths), email addresses
  • 1.9 Test configuration by running cspell --config .cspell.json README.md and verify no false positives are reported for existing markdown files
  • 1.10 Verify configuration file is valid JSON by running python -m json.tool .cspell.json or using check-json pre-commit hook
• 2.0 Add cspell Hook to Pre-commit Configuration
  • Demo Criteria: Hook added to .pre-commit-config.yaml, hook placed after file format checks (after check-toml hook), hook placed before code linting hooks (before ruff-check hook), hook checks markdown files (configured with files: \.md$), CHANGELOG.md excluded (configured with exclude: CHANGELOG\.md), hook execution successful (Pre-commit run cspell passes), hook execution order verified (runs after file format checks, before code linting)
  • Proof Artifact(s): Updated .pre-commit-config.yaml with cspell hook entry, Successful hook execution output showing markdown files checked, Hook execution order verified in config file (after check-toml, before ruff-check), YAML validation passed, Hook installation successful, Hook execution test passed
  • 2.1 Add new repository entry to .pre-commit-config.yaml for cspell using repo: https://github.com/streetsidesoftware/cspell-pre-commit with appropriate rev tag (check latest version)
  • 2.2 Add cspell hook entry with id: cspell in the hooks list, placing it after the pre-commit-hooks repository section (after file format checks) but before the ruff-pre-commit repository section (before code linting)
  • 2.3 Configure hook to check only markdown files by adding files: \.md$ pattern or using appropriate file filtering
  • 2.4 Configure hook to exclude CHANGELOG.md using exclude: CHANGELOG\.md pattern (matching markdownlint exclusion pattern)
  • 2.5 Verify hook placement in config file: cspell hook should appear after check-toml hook and before ruff-check hook
  • 2.6 Test hook installation by running pre-commit install (or verify it's already installed)
  • 2.7 Test hook execution by running pre-commit run cspell --all-files and verify it checks markdown files successfully
  • 2.8 Verify hook execution order by running pre-commit run --all-files and confirming cspell runs after file format checks and before code linting
• 3.0 Verify Pre-commit Hook Failure Behavior
  • Demo Criteria: Test file created test-spell-check.md with intentional spelling errors, Commit fails (Exit code 1 when spelling errors are present), Error message shows misspelled words ("recieve" and "seperate" identified), Suggestions provided ("receive" and "separate" suggested as fixes), File clearly identified (test-spell-check.md shown in error output), Line numbers provided (Line 9 and line 10 indicated), Commit succeeds after fix (All hooks pass when errors are corrected), Test file removed (Cleanup completed successfully)
  • Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, Test markdown file with intentional errors (created and removed), Successful commit after fixing errors, Error output clearly indicates file, line numbers, and misspelled words, Suggestions provided for each misspelled word
  • 3.1 Create a temporary test markdown file test-spell-check.md with intentional spelling errors (e.g., "teh" instead of "the", "receive" instead of "receive")
  • 3.2 Stage the test file: git add test-spell-check.md
  • 3.3 Attempt to commit the file: git commit -m "test: verify cspell hook failure behavior"
  • 3.4 Verify commit fails with cspell error message showing misspelled words and suggestions
  • 3.5 Verify error output clearly indicates which file contains spelling errors and lists misspelled words
  • 3.6 Fix spelling errors in test file and verify commit succeeds
  • 3.7 Remove test file after verification: git rm test-spell-check.md && git commit -m "test: remove spell check test file"
  • 3.8 Document the failure behavior verification process (can be included in CONTRIBUTING.md update)
• 4.0 Update Documentation for Spell Checker
  • Demo Criteria: Spell Checking section added (New subsection under "Pre-commit Hooks"), Explains cspell hook (Documents that it checks markdown files and fails commits on errors), Dictionary management documented (Instructions for adding new terms to .cspell.json), Verification documented (How to verify spell checking works manually or automatically), CHANGELOG.md exclusion mentioned (Note that it's excluded from spell checking), Pre-commit Hooks summary updated (Includes spell checking in the list), All markdown files pass (Verified with pre-commit run cspell --all-files), Follows CONTRIBUTING.md style (Consistent formatting and structure)
  • Proof Artifact(s): Updated CONTRIBUTING.md with spell checking section, All existing markdown files pass spell checking (no false positives), Documentation follows existing CONTRIBUTING.md structure and style, Pre-commit Hooks section summary updated to include spell checking
  • 4.1 Add new "Spell Checking" subsection under "Pre-commit Hooks" section in CONTRIBUTING.md (after existing hook descriptions)
  • 4.2 Document that cspell checks markdown files for spelling errors and fails commits on errors
  • 4.3 Explain how to add new project-specific terms to .cspell.json dictionary: edit the words array and add the term
  • 4.4 Document how to verify spell checking works: run pre-commit run cspell --all-files or let it run automatically on commit
  • 4.5 Mention that CHANGELOG.md is excluded from spell checking
  • 4.6 Update the "Pre-commit Hooks" section summary to include spell checking in the list of checks
  • 4.7 Verify all existing markdown files pass spell checking by running pre-commit run cspell --all-files and addressing any false positives by adding terms to dictionary
  • 4.8 Ensure documentation follows existing CONTRIBUTING.md style and formatting conventions