Add pre-commit hook for cspell

# 05-spec-pre-commit-cspell.md

## Introduction/Overview

This specification adds a pre-commit hook for cspell (Code Spell Checker) to enforce spelling consistency across markdown documentation files in the repository. The hook will check all markdown files during commits, fail on spelling errors, and provide suggestions for corrections while requiring manual dictionary updates for project-specific terms. This ensures documentation quality and consistency while maintaining developer control over technical terminology.

## Goals

- Integrate cspell as a pre-commit hook to check markdown files automatically
- Create a shared `.cspell.json` configuration file at the repository root
- Provide clear error messages with spelling suggestions when errors are detected
- Include common project-specific terms in the initial dictionary to reduce false positives
- Fail commits when spelling errors are found to maintain documentation quality
- Enable manual dictionary management for project-specific terminology

## User Stories

**As a documentation maintainer**, I want markdown files to be spell-checked automatically so that typos and spelling errors are caught before they reach the repository.

**As a developer**, I want clear feedback on spelling errors with suggestions so that I can quickly fix documentation issues without guessing correct spellings.

**As a project maintainer**, I want project-specific terms (like "Liatrio", "slash-man", "SDD") to be recognized as valid words so that technical terminology doesn't trigger false positives.

**As a contributor**, I want the spell checker to run consistently across all commits so that documentation quality standards are maintained automatically.

## Demoable Units of Work

### [Unit 1]: cspell Pre-commit Hook Integration

**Purpose:** Add cspell hook to the existing pre-commit configuration to check markdown files
**Demo Criteria:** Running `pre-commit run cspell --all-files` successfully checks all markdown files and reports spelling errors (if any exist)
**Proof Artifacts:** Updated `.pre-commit-config.yaml` with cspell hook, successful hook execution output, test: verify hook runs on commit attempt

### [Unit 2]: cspell Configuration File Creation

**Purpose:** Create `.cspell.json` configuration file with project-specific dictionary and markdown file patterns
**Demo Criteria:** 
- File `.cspell.json` exists at repository root
- Configuration includes project-specific terms (Liatrio, slash-man, SDD, MCP, etc.)
- Configuration specifies markdown file patterns (`.md` files)
- Running `cspell --config .cspell.json README.md` validates configuration works
**Proof Artifacts:** Created `.cspell.json` file, cspell command output showing configuration loaded, dictionary terms visible in config

### [Unit 3]: Pre-commit Hook Failure Behavior

**Purpose:** Verify that commits fail when spelling errors are detected in markdown files
**Demo Criteria:** 
- Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the")
- Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`
- Commit fails with cspell error message showing the misspelled word and suggestions
**Proof Artifacts:** Git commit failure output, cspell error message with suggestions, test: verify commit fails on spelling error

### [Unit 4]: Dictionary Management Workflow

**Purpose:** Demonstrate manual dictionary update process for adding project-specific terms
**Demo Criteria:**
- Add a new project-specific term to `.cspell.json` dictionary (e.g., "uvx")
- Verify term is recognized: `cspell --config .cspell.json --words-only "uvx"` returns no errors
- Commit the updated dictionary file successfully
**Proof Artifacts:** Updated `.cspell.json` with new dictionary entry, cspell validation output, successful commit of dictionary changes

## Functional Requirements

1. **The system shall** check all markdown files (`.md` extension) during pre-commit hook execution
2. **The system shall** use a shared `.cspell.json` configuration file located at the repository root
3. **The system shall** fail the commit when spelling errors are detected in markdown files
4. **The system shall** provide spelling suggestions in error messages when misspellings are found
5. **The system shall** recognize project-specific terms defined in the `.cspell.json` dictionary
6. **The system shall** run on all files in the commit (not just changed files) to ensure consistency
7. **The system shall** integrate with the existing pre-commit hook framework without breaking other hooks
8. **The system shall** allow manual updates to the dictionary file for adding new project-specific terms
9. **The system shall** exclude common false-positive patterns (code blocks, URLs, file paths) from spell checking
10. **The system shall** provide clear error output indicating which files contain spelling errors and which words are misspelled

## Non-Goals (Out of Scope)

1. **Spell checking code files** - This feature only checks markdown documentation files, not Python code, comments, or docstrings
2. **Automatic dictionary updates** - Dictionary updates must be manual; the system will not auto-add words to the dictionary
3. **Spell checking during CI/CD** - This is a pre-commit hook only; CI/CD spell checking is out of scope
4. **Integration with IDE spell checkers** - IDE-specific spell checking configuration is not included
5. **Multi-language support** - Only English spell checking is supported
6. **Auto-fixing spelling errors** - The hook reports errors but does not automatically fix them
7. **Spell checking of generated files** - Only source markdown files are checked, not generated documentation

## Design Considerations

No specific design requirements identified. This is a command-line tool integration with no UI components.

## Repository Standards

- **Pre-commit Configuration**: Follow existing `.pre-commit-config.yaml` structure and hook ordering patterns
- **Configuration Files**: Place `.cspell.json` at repository root following standard cspell configuration location
- **Dictionary Management**: Use standard cspell dictionary format with `words` array in JSON configuration
- **Documentation**: Update `CONTRIBUTING.md` to include information about the spell checker and dictionary management
- **Testing**: Follow existing test patterns; add tests to verify hook integration and configuration
- **Commit Messages**: Use conventional commit format (already established in repository)

## Technical Considerations

- **cspell Installation**: cspell will be installed via pre-commit hook framework (no manual installation required)
- **Pre-commit Hook Repository**: Use official cspell pre-commit hook repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- **Configuration Format**: Use JSON format for `.cspell.json` (standard cspell configuration format)
- **File Patterns**: Configure cspell to check only `.md` files using `files` or `include` patterns in configuration
- **Dictionary Format**: Use `words` array in `.cspell.json` for project-specific terms
- **Exclusion Patterns**: Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- **Hook Execution Order**: Place cspell hook after file format checks but before code linting hooks
- **Performance**: cspell should run efficiently on markdown files; consider excluding large generated files if needed
- **Dependencies**: No additional Python dependencies required; cspell runs via pre-commit framework

## Success Metrics

1. **Hook Integration**: Pre-commit hook successfully runs cspell on all markdown files during commit attempts
2. **Error Detection**: Spelling errors in markdown files cause commits to fail with clear error messages
3. **False Positive Reduction**: Initial dictionary includes sufficient project-specific terms to minimize false positives (target: <5% false positive rate on existing markdown files)
4. **Developer Experience**: Developers can successfully add new terms to dictionary and commit changes
5. **Documentation Quality**: All existing markdown files pass spell checking after dictionary configuration

## Open Questions

1. Should we exclude any specific markdown files from spell checking (e.g., CHANGELOG.md, auto-generated docs)?
2. What is the preferred approach for handling technical terms that may vary (e.g., "GitHub" vs "github")?
3. Should we include common technical terms from dependencies (e.g., "pytest", "ruff", "typer") in the initial dictionary?
4. Do we need to configure any specific cspell language dictionaries or versions?

# 05-spec-pre-commit-cspell.md

## Introduction/Overview

This specification adds a pre-commit hook for cspell (Code Spell Checker) to enforce spelling consistency across markdown documentation files in the repository. The hook will check all markdown files during commits, fail on spelling errors, and provide suggestions for corrections while requiring manual dictionary updates for project-specific terms. This ensures documentation quality and consistency while maintaining developer control over technical terminology.

## Goals

- Integrate cspell as a pre-commit hook to check markdown files automatically
- Create a shared `.cspell.json` configuration file at the repository root
- Provide clear error messages with spelling suggestions when errors are detected
- Include common project-specific terms in the initial dictionary to reduce false positives
- Fail commits when spelling errors are found to maintain documentation quality
- Enable manual dictionary management for project-specific terminology

## User Stories

**As a documentation maintainer**, I want markdown files to be spell-checked automatically so that typos and spelling errors are caught before they reach the repository.

**As a developer**, I want clear feedback on spelling errors with suggestions so that I can quickly fix documentation issues without guessing correct spellings.

**As a project maintainer**, I want project-specific terms (like "Liatrio", "slash-man", "SDD") to be recognized as valid words so that technical terminology doesn't trigger false positives.

**As a contributor**, I want the spell checker to run consistently across all commits so that documentation quality standards are maintained automatically.

## Demoable Units of Work

### [Unit 1]: cspell Pre-commit Hook Integration

**Purpose:** Add cspell hook to the existing pre-commit configuration to check markdown files
**Demo Criteria:** Running `pre-commit run cspell --all-files` successfully checks all markdown files and reports spelling errors (if any exist)
**Proof Artifacts:** Updated `.pre-commit-config.yaml` with cspell hook, successful hook execution output, test: verify hook runs on commit attempt

### [Unit 2]: cspell Configuration File Creation

**Purpose:** Create `.cspell.json` configuration file with project-specific dictionary and markdown file patterns
**Demo Criteria:** 
- File `.cspell.json` exists at repository root
- Configuration includes project-specific terms (Liatrio, slash-man, SDD, MCP, etc.)
- Configuration specifies markdown file patterns (`.md` files)
- Running `cspell --config .cspell.json README.md` validates configuration works
**Proof Artifacts:** Created `.cspell.json` file, cspell command output showing configuration loaded, dictionary terms visible in config

### [Unit 3]: Pre-commit Hook Failure Behavior

**Purpose:** Verify that commits fail when spelling errors are detected in markdown files
**Demo Criteria:** 
- Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the")
- Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`
- Commit fails with cspell error message showing the misspelled word and suggestions
**Proof Artifacts:** Git commit failure output, cspell error message with suggestions, test: verify commit fails on spelling error

### [Unit 4]: Dictionary Management Workflow

**Purpose:** Demonstrate manual dictionary update process for adding project-specific terms
**Demo Criteria:**
- Add a new project-specific term to `.cspell.json` dictionary (e.g., "uvx")
- Verify term is recognized: `cspell --config .cspell.json --words-only "uvx"` returns no errors
- Commit the updated dictionary file successfully
**Proof Artifacts:** Updated `.cspell.json` with new dictionary entry, cspell validation output, successful commit of dictionary changes

## Functional Requirements

1. **The system shall** check all markdown files (`.md` extension) during pre-commit hook execution
2. **The system shall** use a shared `.cspell.json` configuration file located at the repository root
3. **The system shall** fail the commit when spelling errors are detected in markdown files
4. **The system shall** provide spelling suggestions in error messages when misspellings are found
5. **The system shall** recognize project-specific terms defined in the `.cspell.json` dictionary
6. **The system shall** run on all files in the commit (not just changed files) to ensure consistency
7. **The system shall** integrate with the existing pre-commit hook framework without breaking other hooks
8. **The system shall** allow manual updates to the dictionary file for adding new project-specific terms
9. **The system shall** exclude common false-positive patterns (code blocks, URLs, file paths) from spell checking
10. **The system shall** provide clear error output indicating which files contain spelling errors and which words are misspelled

## Non-Goals (Out of Scope)

1. **Spell checking code files** - This feature only checks markdown documentation files, not Python code, comments, or docstrings
2. **Automatic dictionary updates** - Dictionary updates must be manual; the system will not auto-add words to the dictionary
3. **Spell checking during CI/CD** - This is a pre-commit hook only; CI/CD spell checking is out of scope
4. **Integration with IDE spell checkers** - IDE-specific spell checking configuration is not included
5. **Multi-language support** - Only English spell checking is supported
6. **Auto-fixing spelling errors** - The hook reports errors but does not automatically fix them
7. **Spell checking of generated files** - Only source markdown files are checked, not generated documentation
8. **Spell checking CHANGELOG.md** - CHANGELOG.md is excluded from spell checking as it may contain inconsistent formatting and auto-generated content

## Design Considerations

No specific design requirements identified. This is a command-line tool integration with no UI components.

## Repository Standards

- **Pre-commit Configuration**: Follow existing `.pre-commit-config.yaml` structure and hook ordering patterns
- **Configuration Files**: Place `.cspell.json` at repository root following standard cspell configuration location
- **Dictionary Management**: Use standard cspell dictionary format with `words` array in JSON configuration
- **Documentation**: Update `CONTRIBUTING.md` to include information about the spell checker and dictionary management
- **Testing**: Follow existing test patterns; add tests to verify hook integration and configuration
- **Commit Messages**: Use conventional commit format (already established in repository)

## Technical Considerations

- **cspell Installation**: cspell will be installed via pre-commit hook framework (no manual installation required)
- **Pre-commit Hook Repository**: Use official cspell pre-commit hook repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- **Configuration Format**: Use JSON format for `.cspell.json` (standard cspell configuration format)
- **File Patterns**: Configure cspell to check only `.md` files using `files` or `include` patterns in configuration
- **Dictionary Format**: Use `words` array in `.cspell.json` for project-specific terms
- **Exclusion Patterns**: Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- **Hook Execution Order**: Place cspell hook after file format checks but before code linting hooks
- **Performance**: cspell should run efficiently on markdown files; consider excluding large generated files if needed
- **Dependencies**: No additional Python dependencies required; cspell runs via pre-commit framework

## Success Metrics

1. **Hook Integration**: Pre-commit hook successfully runs cspell on all markdown files during commit attempts
2. **Error Detection**: Spelling errors in markdown files cause commits to fail with clear error messages
3. **False Positive Reduction**: Initial dictionary includes sufficient project-specific terms to minimize false positives (target: <5% false positive rate on existing markdown files)
4. **Developer Experience**: Developers can successfully add new terms to dictionary and commit changes
5. **Documentation Quality**: All existing markdown files pass spell checking after dictionary configuration

## Open Questions

1. Should we exclude any specific markdown files from spell checking (e.g., CHANGELOG.md, auto-generated docs)?
    whatever you recommend
2. What is the preferred approach for handling technical terms that may vary (e.g., "GitHub" vs "github")?
    whatever you recommend
3. Should we include common technical terms from dependencies (e.g., "pytest", "ruff", "typer") in the initial dictionary?
    whatever you recommend
4. Do we need to configure any specific cspell language dictionaries or versions?
    whatever you recommend

# 05-spec-pre-commit-cspell.md

## Introduction/Overview

This specification adds a pre-commit hook for cspell (Code Spell Checker) to enforce spelling consistency across markdown documentation files in the repository. The hook will check all markdown files during commits, fail on spelling errors, and provide suggestions for corrections while requiring manual dictionary updates for project-specific terms. This ensures documentation quality and consistency while maintaining developer control over technical terminology.

## Goals

- Integrate cspell as a pre-commit hook to check markdown files automatically
- Create a shared `.cspell.json` configuration file at the repository root
- Provide clear error messages with spelling suggestions when errors are detected
- Include common project-specific terms in the initial dictionary to reduce false positives
- Fail commits when spelling errors are found to maintain documentation quality
- Enable manual dictionary management for project-specific terminology

## User Stories

**As a documentation maintainer**, I want markdown files to be spell-checked automatically so that typos and spelling errors are caught before they reach the repository.

**As a developer**, I want clear feedback on spelling errors with suggestions so that I can quickly fix documentation issues without guessing correct spellings.

**As a project maintainer**, I want project-specific terms (like "Liatrio", "slash-man", "SDD") to be recognized as valid words so that technical terminology doesn't trigger false positives.

**As a contributor**, I want the spell checker to run consistently across all commits so that documentation quality standards are maintained automatically.

## Demoable Units of Work

### [Unit 1]: cspell Pre-commit Hook Integration

**Purpose:** Add cspell hook to the existing pre-commit configuration to check markdown files
**Demo Criteria:** Running `pre-commit run cspell --all-files` successfully checks all markdown files and reports spelling errors (if any exist)
**Proof Artifacts:** Updated `.pre-commit-config.yaml` with cspell hook, successful hook execution output, test: verify hook runs on commit attempt

### [Unit 2]: cspell Configuration File Creation

**Purpose:** Create `.cspell.json` configuration file with project-specific dictionary and markdown file patterns
**Demo Criteria:** 
- File `.cspell.json` exists at repository root
- Configuration includes project-specific terms (Liatrio, slash-man, SDD, MCP, etc.)
- Configuration specifies markdown file patterns (`.md` files)
- Running `cspell --config .cspell.json README.md` validates configuration works
**Proof Artifacts:** Created `.cspell.json` file, cspell command output showing configuration loaded, dictionary terms visible in config

### [Unit 3]: Pre-commit Hook Failure Behavior

**Purpose:** Verify that commits fail when spelling errors are detected in markdown files
**Demo Criteria:** 
- Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the")
- Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`
- Commit fails with cspell error message showing the misspelled word and suggestions
**Proof Artifacts:** Git commit failure output, cspell error message with suggestions, test: verify commit fails on spelling error

### [Unit 4]: Dictionary Management Workflow

**Purpose:** Demonstrate manual dictionary update process for adding project-specific terms
**Demo Criteria:**
- Add a new project-specific term to `.cspell.json` dictionary (e.g., "uvx")
- Verify term is recognized: `cspell --config .cspell.json --words-only "uvx"` returns no errors
- Commit the updated dictionary file successfully
**Proof Artifacts:** Updated `.cspell.json` with new dictionary entry, cspell validation output, successful commit of dictionary changes

## Functional Requirements

1. **The system shall** check all markdown files (`.md` extension) during pre-commit hook execution
2. **The system shall** use a shared `.cspell.json` configuration file located at the repository root
3. **The system shall** fail the commit when spelling errors are detected in markdown files
4. **The system shall** provide spelling suggestions in error messages when misspellings are found
5. **The system shall** recognize project-specific terms defined in the `.cspell.json` dictionary
6. **The system shall** run on all files in the commit (not just changed files) to ensure consistency
7. **The system shall** integrate with the existing pre-commit hook framework without breaking other hooks
8. **The system shall** allow manual updates to the dictionary file for adding new project-specific terms
9. **The system shall** exclude common false-positive patterns (code blocks, URLs, file paths) from spell checking
10. **The system shall** provide clear error output indicating which files contain spelling errors and which words are misspelled

## Non-Goals (Out of Scope)

1. **Spell checking code files** - This feature only checks markdown documentation files, not Python code, comments, or docstrings
2. **Automatic dictionary updates** - Dictionary updates must be manual; the system will not auto-add words to the dictionary
3. **Spell checking during CI/CD** - This is a pre-commit hook only; CI/CD spell checking is out of scope
4. **Integration with IDE spell checkers** - IDE-specific spell checking configuration is not included
5. **Multi-language support** - Only English spell checking is supported
6. **Auto-fixing spelling errors** - The hook reports errors but does not automatically fix them
7. **Spell checking of generated files** - Only source markdown files are checked, not generated documentation
8. **Spell checking CHANGELOG.md** - CHANGELOG.md is excluded from spell checking as it may contain inconsistent formatting and auto-generated content

## Design Considerations

No specific design requirements identified. This is a command-line tool integration with no UI components.

## Repository Standards

- **Pre-commit Configuration**: Follow existing `.pre-commit-config.yaml` structure and hook ordering patterns
- **Configuration Files**: Place `.cspell.json` at repository root following standard cspell configuration location
- **Dictionary Management**: Use standard cspell dictionary format with `words` array in JSON configuration
- **Documentation**: Update `CONTRIBUTING.md` to include information about the spell checker and dictionary management
- **Testing**: Follow existing test patterns; add tests to verify hook integration and configuration
- **Commit Messages**: Use conventional commit format (already established in repository)

## Technical Considerations

- **cspell Installation**: cspell will be installed via pre-commit hook framework (no manual installation required)
- **Pre-commit Hook Repository**: Use official cspell pre-commit hook repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- **Configuration Format**: Use JSON format for `.cspell.json` (standard cspell configuration format)
- **File Patterns**: Configure cspell to check only `.md` files using `files` or `include` patterns in configuration
- **File Exclusions**: Exclude `CHANGELOG.md` from spell checking (auto-generated content with potentially inconsistent formatting)
- **Dictionary Format**: Use `words` array in `.cspell.json` for project-specific terms
- **Initial Dictionary**: Include common project-specific terms (Liatrio, slash-man, SDD, MCP, etc.) and dependency names (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- **Technical Term Capitalization**: Use standard proper capitalization for technical terms (e.g., "GitHub", "Python", "JSON", "YAML", "CLI", "MCP")
- **Language Dictionary**: Use default English (en_US) dictionary provided by cspell
- **Exclusion Patterns**: Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- **Hook Execution Order**: Place cspell hook after file format checks but before code linting hooks
- **Performance**: cspell should run efficiently on markdown files; consider excluding large generated files if needed
- **Dependencies**: No additional Python dependencies required; cspell runs via pre-commit framework

## Success Metrics

1. **Hook Integration**: Pre-commit hook successfully runs cspell on all markdown files during commit attempts
2. **Error Detection**: Spelling errors in markdown files cause commits to fail with clear error messages
3. **False Positive Reduction**: Initial dictionary includes sufficient project-specific terms to minimize false positives (target: <5% false positive rate on existing markdown files)
4. **Developer Experience**: Developers can successfully add new terms to dictionary and commit changes
5. **Documentation Quality**: All existing markdown files pass spell checking after dictionary configuration

## Open Questions

1. Should we exclude any specific markdown files from spell checking (e.g., CHANGELOG.md, auto-generated docs)?
    whatever you recommend
2. What is the preferred approach for handling technical terms that may vary (e.g., "GitHub" vs "github")?
    whatever you recommend
3. Should we include common technical terms from dependencies (e.g., "pytest", "ruff", "typer") in the initial dictionary?
    whatever you recommend
4. Do we need to configure any specific cspell language dictionaries or versions?
    whatever you recommend

# 05-spec-pre-commit-cspell.md

## Introduction/Overview

This specification adds a pre-commit hook for cspell (Code Spell Checker) to enforce spelling consistency across markdown documentation files in the repository. The hook will check all markdown files during commits, fail on spelling errors, and provide suggestions for corrections while requiring manual dictionary updates for project-specific terms. This ensures documentation quality and consistency while maintaining developer control over technical terminology.

## Goals

- Integrate cspell as a pre-commit hook to check markdown files automatically
- Create a shared `.cspell.json` configuration file at the repository root
- Provide clear error messages with spelling suggestions when errors are detected
- Include common project-specific terms in the initial dictionary to reduce false positives
- Fail commits when spelling errors are found to maintain documentation quality
- Enable manual dictionary management for project-specific terminology

## User Stories

**As a documentation maintainer**, I want markdown files to be spell-checked automatically so that typos and spelling errors are caught before they reach the repository.

**As a developer**, I want clear feedback on spelling errors with suggestions so that I can quickly fix documentation issues without guessing correct spellings.

**As a project maintainer**, I want project-specific terms (like "Liatrio", "slash-man", "SDD") to be recognized as valid words so that technical terminology doesn't trigger false positives.

**As a contributor**, I want the spell checker to run consistently across all commits so that documentation quality standards are maintained automatically.

## Demoable Units of Work

### [Unit 1]: cspell Pre-commit Hook Integration

**Purpose:** Add cspell hook to the existing pre-commit configuration to check markdown files
**Demo Criteria:** Running `pre-commit run cspell --all-files` successfully checks all markdown files and reports spelling errors (if any exist)
**Proof Artifacts:** Updated `.pre-commit-config.yaml` with cspell hook, successful hook execution output, test: verify hook runs on commit attempt

### [Unit 2]: cspell Configuration File Creation

**Purpose:** Create `.cspell.json` configuration file with project-specific dictionary and markdown file patterns
**Demo Criteria:** 
- File `.cspell.json` exists at repository root
- Configuration includes project-specific terms (Liatrio, slash-man, SDD, MCP, etc.)
- Configuration specifies markdown file patterns (`.md` files)
- Running `cspell --config .cspell.json README.md` validates configuration works
**Proof Artifacts:** Created `.cspell.json` file, cspell command output showing configuration loaded, dictionary terms visible in config

### [Unit 3]: Pre-commit Hook Failure Behavior

**Purpose:** Verify that commits fail when spelling errors are detected in markdown files
**Demo Criteria:** 
- Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the")
- Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`
- Commit fails with cspell error message showing the misspelled word and suggestions
**Proof Artifacts:** Git commit failure output, cspell error message with suggestions, test: verify commit fails on spelling error

### [Unit 4]: Dictionary Management Workflow

**Purpose:** Demonstrate manual dictionary update process for adding project-specific terms
**Demo Criteria:**
- Add a new project-specific term to `.cspell.json` dictionary (e.g., "uvx")
- Verify term is recognized: `cspell --config .cspell.json --words-only "uvx"` returns no errors
- Commit the updated dictionary file successfully
**Proof Artifacts:** Updated `.cspell.json` with new dictionary entry, cspell validation output, successful commit of dictionary changes

## Functional Requirements

1. **The system shall** check all markdown files (`.md` extension) during pre-commit hook execution
2. **The system shall** use a shared `.cspell.json` configuration file located at the repository root
3. **The system shall** fail the commit when spelling errors are detected in markdown files
4. **The system shall** provide spelling suggestions in error messages when misspellings are found
5. **The system shall** recognize project-specific terms defined in the `.cspell.json` dictionary
6. **The system shall** run on all files in the commit (not just changed files) to ensure consistency
7. **The system shall** integrate with the existing pre-commit hook framework without breaking other hooks
8. **The system shall** allow manual updates to the dictionary file for adding new project-specific terms
9. **The system shall** exclude common false-positive patterns (code blocks, URLs, file paths) from spell checking
10. **The system shall** provide clear error output indicating which files contain spelling errors and which words are misspelled

## Non-Goals (Out of Scope)

1. **Spell checking code files** - This feature only checks markdown documentation files, not Python code, comments, or docstrings
2. **Automatic dictionary updates** - Dictionary updates must be manual; the system will not auto-add words to the dictionary
3. **Spell checking during CI/CD** - This is a pre-commit hook only; CI/CD spell checking is out of scope
4. **Integration with IDE spell checkers** - IDE-specific spell checking configuration is not included
5. **Multi-language support** - Only English spell checking is supported
6. **Auto-fixing spelling errors** - The hook reports errors but does not automatically fix them
7. **Spell checking of generated files** - Only source markdown files are checked, not generated documentation
8. **Spell checking CHANGELOG.md** - CHANGELOG.md is excluded from spell checking as it may contain inconsistent formatting and auto-generated content

## Design Considerations

No specific design requirements identified. This is a command-line tool integration with no UI components.

## Repository Standards

- **Pre-commit Configuration**: Follow existing `.pre-commit-config.yaml` structure and hook ordering patterns
- **Configuration Files**: Place `.cspell.json` at repository root following standard cspell configuration location
- **Dictionary Management**: Use standard cspell dictionary format with `words` array in JSON configuration
- **Documentation**: Update `CONTRIBUTING.md` to include information about the spell checker and dictionary management
- **Testing**: Follow existing test patterns; add tests to verify hook integration and configuration
- **Commit Messages**: Use conventional commit format (already established in repository)

## Technical Considerations

- **cspell Installation**: cspell will be installed via pre-commit hook framework (no manual installation required)
- **Pre-commit Hook Repository**: Use official cspell pre-commit hook repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- **Configuration Format**: Use JSON format for `.cspell.json` (standard cspell configuration format)
- **File Patterns**: Configure cspell to check only `.md` files using `files` or `include` patterns in configuration
- **File Exclusions**: Exclude `CHANGELOG.md` from spell checking (auto-generated content with potentially inconsistent formatting)
- **Dictionary Format**: Use `words` array in `.cspell.json` for project-specific terms
- **Initial Dictionary**: Include common project-specific terms (Liatrio, slash-man, SDD, MCP, etc.) and dependency names (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- **Technical Term Capitalization**: Use standard proper capitalization for technical terms (e.g., "GitHub", "Python", "JSON", "YAML", "CLI", "MCP")
- **Language Dictionary**: Use default English (en_US) dictionary provided by cspell
- **Exclusion Patterns**: Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- **Hook Execution Order**: Place cspell hook after file format checks but before code linting hooks
- **Performance**: cspell should run efficiently on markdown files; consider excluding large generated files if needed
- **Dependencies**: No additional Python dependencies required; cspell runs via pre-commit framework

## Success Metrics

1. **Hook Integration**: Pre-commit hook successfully runs cspell on all markdown files during commit attempts
2. **Error Detection**: Spelling errors in markdown files cause commits to fail with clear error messages
3. **False Positive Reduction**: Initial dictionary includes sufficient project-specific terms to minimize false positives (target: <5% false positive rate on existing markdown files)
4. **Developer Experience**: Developers can successfully add new terms to dictionary and commit changes
5. **Documentation Quality**: All existing markdown files pass spell checking after dictionary configuration

## Open Questions

No open questions at this time.

# 05-spec-pre-commit-cspell.md

## Introduction/Overview

This specification adds a pre-commit hook for cspell (Code Spell Checker) to enforce spelling consistency across markdown documentation files in the repository. The hook will check all markdown files during commits, fail on spelling errors, and provide suggestions for corrections while requiring manual dictionary updates for project-specific terms. This ensures documentation quality and consistency while maintaining developer control over technical terminology.

## Goals

- Integrate cspell as a pre-commit hook to check markdown files automatically
- Create a shared `.cspell.json` configuration file at the repository root
- Provide clear error messages with spelling suggestions when errors are detected
- Include common project-specific terms in the initial dictionary to reduce false positives
- Fail commits when spelling errors are found to maintain documentation quality
- Enable manual dictionary management for project-specific terminology

## User Stories

**As a documentation maintainer**, I want markdown files to be spell-checked automatically so that typos and spelling errors are caught before they reach the repository.

**As a developer**, I want clear feedback on spelling errors with suggestions so that I can quickly fix documentation issues without guessing correct spellings.

**As a project maintainer**, I want project-specific terms (like "Liatrio", "slash-man", "SDD") to be recognized as valid words so that technical terminology doesn't trigger false positives.

**As a contributor**, I want the spell checker to run consistently across all commits so that documentation quality standards are maintained automatically.

## Demoable Units of Work

### [Unit 1]: cspell Pre-commit Hook Integration

**Purpose:** Add cspell hook to the existing pre-commit configuration to check markdown files
**Demo Criteria:** Running `pre-commit run cspell --all-files` successfully checks all markdown files and reports spelling errors (if any exist)
**Proof Artifacts:** Updated `.pre-commit-config.yaml` with cspell hook, successful hook execution output, test: verify hook runs on commit attempt

### [Unit 2]: cspell Configuration File Creation

**Purpose:** Create `.cspell.json` configuration file with project-specific dictionary and markdown file patterns
**Demo Criteria:** 
- File `.cspell.json` exists at repository root
- Configuration includes project-specific terms (Liatrio, slash-man, SDD, MCP, etc.)
- Configuration specifies markdown file patterns (`.md` files)
- Running `cspell --config .cspell.json README.md` validates configuration works
**Proof Artifacts:** Created `.cspell.json` file, cspell command output showing configuration loaded, dictionary terms visible in config

### [Unit 3]: Pre-commit Hook Failure Behavior

**Purpose:** Verify that commits fail when spelling errors are detected in markdown files
**Demo Criteria:** 
- Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the")
- Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`
- Commit fails with cspell error message showing the misspelled word and suggestions
**Proof Artifacts:** Git commit failure output, cspell error message with suggestions, test: verify commit fails on spelling error

### [Unit 4]: Dictionary Management Workflow

**Purpose:** Demonstrate manual dictionary update process for adding project-specific terms
**Demo Criteria:**
- Add a new project-specific term to `.cspell.json` dictionary (e.g., "uvx")
- Verify term is recognized: `cspell --config .cspell.json --words-only "uvx"` returns no errors
- Commit the updated dictionary file successfully
**Proof Artifacts:** Updated `.cspell.json` with new dictionary entry, cspell validation output, successful commit of dictionary changes

## Functional Requirements

1. **The system shall** check all markdown files (`.md` extension) during pre-commit hook execution, excluding `CHANGELOG.md`
2. **The system shall** use a shared `.cspell.json` configuration file located at the repository root
3. **The system shall** fail the commit when spelling errors are detected in markdown files
4. **The system shall** provide spelling suggestions in error messages when misspellings are found
5. **The system shall** recognize project-specific terms defined in the `.cspell.json` dictionary
6. **The system shall** run on all files in the commit (not just changed files) to ensure consistency
7. **The system shall** integrate with the existing pre-commit hook framework without breaking other hooks
8. **The system shall** allow manual updates to the dictionary file for adding new project-specific terms
9. **The system shall** exclude common false-positive patterns (code blocks, URLs, file paths) from spell checking
10. **The system shall** provide clear error output indicating which files contain spelling errors and which words are misspelled
11. **The system shall** use standard English (en_US) dictionary and proper capitalization for technical terms

## Non-Goals (Out of Scope)

1. **Spell checking code files** - This feature only checks markdown documentation files, not Python code, comments, or docstrings
2. **Automatic dictionary updates** - Dictionary updates must be manual; the system will not auto-add words to the dictionary
3. **Spell checking during CI/CD** - This is a pre-commit hook only; CI/CD spell checking is out of scope
4. **Integration with IDE spell checkers** - IDE-specific spell checking configuration is not included
5. **Multi-language support** - Only English spell checking is supported
6. **Auto-fixing spelling errors** - The hook reports errors but does not automatically fix them
7. **Spell checking of generated files** - Only source markdown files are checked, not generated documentation
8. **Spell checking CHANGELOG.md** - CHANGELOG.md is excluded from spell checking as it may contain inconsistent formatting and auto-generated content

## Design Considerations

No specific design requirements identified. This is a command-line tool integration with no UI components.

## Repository Standards

- **Pre-commit Configuration**: Follow existing `.pre-commit-config.yaml` structure and hook ordering patterns
- **Configuration Files**: Place `.cspell.json` at repository root following standard cspell configuration location
- **Dictionary Management**: Use standard cspell dictionary format with `words` array in JSON configuration
- **Documentation**: Update `CONTRIBUTING.md` to include information about the spell checker and dictionary management
- **Testing**: Follow existing test patterns; add tests to verify hook integration and configuration
- **Commit Messages**: Use conventional commit format (already established in repository)

## Technical Considerations

- **cspell Installation**: cspell will be installed via pre-commit hook framework (no manual installation required)
- **Pre-commit Hook Repository**: Use official cspell pre-commit hook repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- **Configuration Format**: Use JSON format for `.cspell.json` (standard cspell configuration format)
- **File Patterns**: Configure cspell to check only `.md` files using `files` or `include` patterns in configuration
- **File Exclusions**: Exclude `CHANGELOG.md` from spell checking (auto-generated content with potentially inconsistent formatting)
- **Dictionary Format**: Use `words` array in `.cspell.json` for project-specific terms
- **Initial Dictionary**: Include common project-specific terms (Liatrio, slash-man, SDD, MCP, etc.) and dependency names (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- **Technical Term Capitalization**: Use standard proper capitalization for technical terms (e.g., "GitHub", "Python", "JSON", "YAML", "CLI", "MCP")
- **Language Dictionary**: Use default English (en_US) dictionary provided by cspell
- **Exclusion Patterns**: Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- **Hook Execution Order**: Place cspell hook after file format checks but before code linting hooks
- **Performance**: cspell should run efficiently on markdown files; consider excluding large generated files if needed
- **Dependencies**: No additional Python dependencies required; cspell runs via pre-commit framework

## Success Metrics

1. **Hook Integration**: Pre-commit hook successfully runs cspell on all markdown files during commit attempts
2. **Error Detection**: Spelling errors in markdown files cause commits to fail with clear error messages
3. **False Positive Reduction**: Initial dictionary includes sufficient project-specific terms to minimize false positives (target: <5% false positive rate on existing markdown files)
4. **Developer Experience**: Developers can successfully add new terms to dictionary and commit changes
5. **Documentation Quality**: All existing markdown files pass spell checking after dictionary configuration

## Open Questions

No open questions at this time.

# 05-tasks-pre-commit-cspell.md

## 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, dictionary terms visible in config file, test: verify configuration file structure and content

- [ ] 2.0 Add cspell Hook to Pre-commit Configuration
  - Demo Criteria: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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, test: verify hook runs on commit attempt

- [ ] 3.0 Verify Pre-commit Hook Failure Behavior
  - Demo Criteria: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error, test: verify commit fails on spelling error

- [ ] 4.0 Update Documentation for Spell Checker
  - Demo Criteria: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation
- Tests can be manual verification or simple file structure validation tests

## 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, dictionary terms visible in config file, test: verify configuration file structure and content
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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, test: verify hook runs on commit attempt
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error, test: verify commit fails on spelling error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate
  - [ ] 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

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file, test: verify configuration file structure and content
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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, test: verify hook runs on commit attempt
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error, test: verify commit fails on spelling error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate
  - [ ] 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

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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, test: verify hook runs on commit attempt
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error, test: verify commit fails on spelling error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate
  - [ ] 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

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error, test: verify commit fails on spelling error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate
  - [ ] 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

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives), test: verify documentation updates are complete and accurate
  - [ ] 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

# 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
- `tests/test_cspell_config.py` - New test file to verify cspell configuration structure and content (optional, for validation)

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [ ] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [~] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

{
  "version": "0.2",
  "language": "en",
  "files": ["**/*.md"],
  "ignorePaths": [
    "CHANGELOG.md",
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**",
    "htmlcov/**"
  ],
  "words": [
    "Liatrio",
    "slash-man",
    "SDD",
    "MCP",
    "spec-driven",
    "liatrio-labs",
    "pytest",
    "ruff",
    "typer",
    "fastmcp",
    "questionary",
    "uvx",
    "uv",
    "pyyaml",
    "tomli",
    "hatchling",
    "semantic-release",
    "commitlint",
    "markdownlint",
    "GitHub",
    "Python",
    "JSON",
    "YAML",
    "CLI",
    "MCP",
    "HTTP",
    "STDIO",
    "PyPI",
    "CI",
    "CD",
    "API",
    "REST"
  ],
  "flagWords": [],
  "ignoreRegExpList": [
    "/```[\\s\\S]*?```/g",
    "/https?:\\/\\/[^\\s]+/g",
    "/[\\/\\\\][^\\s]+/g",
    "/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g"
  ]
}

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## 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, dictionary terms visible in config file
  - [x] 1.1 Create `.cspell.json` file at repository root with basic structure including `version`, `language`, `files`, `ignorePaths`, `words`, and `flagWords` fields
  - [x] 1.2 Configure `language` field to use `["en"]` for English dictionary
  - [x] 1.3 Configure `files` field to include markdown file patterns: `["**/*.md"]`
  - [x] 1.4 Configure `ignorePaths` field to exclude `CHANGELOG.md` from spell checking
  - [x] 1.5 Add project-specific terms to `words` array: "Liatrio", "slash-man", "SDD", "MCP", "spec-driven", "liatrio-labs"
  - [x] 1.6 Add dependency names to `words` array: "pytest", "ruff", "typer", "fastmcp", "questionary", "uvx", "uv", "pyyaml", "tomli", "hatchling", "semantic-release", "commitlint", "markdownlint"
  - [x] 1.7 Add properly capitalized technical terms to `words` array: "GitHub", "Python", "JSON", "YAML", "CLI", "MCP", "HTTP", "STDIO", "PyPI", "CI", "CD", "API", "REST"
  - [x] 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
  - [x] 1.9 Test configuration by running `cspell --config .cspell.json README.md` and verify no false positives are reported for existing markdown files
  - [x] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

# 05-task-01-proofs.md

## Task 1.0: Create cspell Configuration File

### Configuration File Created

The `.cspell.json` file has been created at the repository root with all required configuration.

### Configuration File Content

```json
{
  "version": "0.2",
  "language": "en",
  "files": ["**/*.md"],
  "ignorePaths": [
    "CHANGELOG.md",
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**",
    "htmlcov/**"
  ],
  "words": [
    "Liatrio",
    "slash-man",
    "SDD",
    "MCP",
    "spec-driven",
    "liatrio-labs",
    "pytest",
    "ruff",
    "typer",
    "fastmcp",
    "questionary",
    "uvx",
    "uv",
    "pyyaml",
    "tomli",
    "hatchling",
    "semantic-release",
    "commitlint",
    "markdownlint",
    "GitHub",
    "Python",
    "JSON",
    "YAML",
    "CLI",
    "MCP",
    "HTTP",
    "STDIO",
    "PyPI",
    "CI",
    "CD",
    "API",
    "REST"
  ],
  "flagWords": [],
  "ignoreRegExpList": [
    "/```[\\s\\S]*?```/g",
    "/https?:\\/\\/[^\\s]+/g",
    "/[\\/\\\\][^\\s]+/g",
    "/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g"
  ]
}

$ python -m json.tool .cspell.json > /dev/null && echo "JSON is valid"
JSON is valid

$ pre-commit run check-json --files .cspell.json
check json...............................................................Passed

$ cspell --config .cspell.json README.md
1/1 README.md 564.98ms
CSpell: Files checked: 1, Issues found: 0 in 0 files.

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## Tasks

- [x] 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, dictionary terms visible in config file
  - [x] 1.1 Create `.cspell.json` file at repository root with basic structure including `version`, `language`, `files`, `ignorePaths`, `words`, and `flagWords` fields
  - [x] 1.2 Configure `language` field to use `["en"]` for English dictionary
  - [x] 1.3 Configure `files` field to include markdown file patterns: `["**/*.md"]`
  - [x] 1.4 Configure `ignorePaths` field to exclude `CHANGELOG.md` from spell checking
  - [x] 1.5 Add project-specific terms to `words` array: "Liatrio", "slash-man", "SDD", "MCP", "spec-driven", "liatrio-labs"
  - [x] 1.6 Add dependency names to `words` array: "pytest", "ruff", "typer", "fastmcp", "questionary", "uvx", "uv", "pyyaml", "tomli", "hatchling", "semantic-release", "commitlint", "markdownlint"
  - [x] 1.7 Add properly capitalized technical terms to `words` array: "GitHub", "Python", "JSON", "YAML", "CLI", "MCP", "HTTP", "STDIO", "PyPI", "CI", "CD", "API", "REST"
  - [x] 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
  - [x] 1.9 Test configuration by running `cspell --config .cspell.json README.md` and verify no false positives are reported for existing markdown files
  - [x] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [ ] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

# 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

### Notes

- The `.cspell.json` file should be created at the repository root following standard cspell configuration format
- The cspell hook should be added to `.pre-commit-config.yaml` using the official repository: `https://github.com/streetsidesoftware/cspell-pre-commit`
- Hook execution order: cspell should run after file format checks (check-yaml, check-json, check-toml) but before code linting hooks (ruff-check, ruff-format)
- The cspell configuration should exclude `CHANGELOG.md` from spell checking (similar to how markdownlint excludes it)
- Project-specific terms should include: Liatrio, slash-man, SDD, MCP, and dependency names from pyproject.toml (pytest, ruff, typer, fastmcp, questionary, uvx, uv, etc.)
- Technical terms should use proper capitalization: GitHub, Python, JSON, YAML, CLI, MCP
- Use standard English (en_US) dictionary provided by cspell
- Configure exclusions for code blocks, URLs, and file paths to reduce false positives
- Follow existing CONTRIBUTING.md structure and style when adding spell checking documentation

## Tasks

- [x] 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, dictionary terms visible in config file
  - [x] 1.1 Create `.cspell.json` file at repository root with basic structure including `version`, `language`, `files`, `ignorePaths`, `words`, and `flagWords` fields
  - [x] 1.2 Configure `language` field to use `["en"]` for English dictionary
  - [x] 1.3 Configure `files` field to include markdown file patterns: `["**/*.md"]`
  - [x] 1.4 Configure `ignorePaths` field to exclude `CHANGELOG.md` from spell checking
  - [x] 1.5 Add project-specific terms to `words` array: "Liatrio", "slash-man", "SDD", "MCP", "spec-driven", "liatrio-labs"
  - [x] 1.6 Add dependency names to `words` array: "pytest", "ruff", "typer", "fastmcp", "questionary", "uvx", "uv", "pyyaml", "tomli", "hatchling", "semantic-release", "commitlint", "markdownlint"
  - [x] 1.7 Add properly capitalized technical terms to `words` array: "GitHub", "Python", "JSON", "YAML", "CLI", "MCP", "HTTP", "STDIO", "PyPI", "CI", "CD", "API", "REST"
  - [x] 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
  - [x] 1.9 Test configuration by running `cspell --config .cspell.json README.md` and verify no false positives are reported for existing markdown files
  - [x] 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: Running `pre-commit run cspell --all-files` successfully checks all markdown files (excluding CHANGELOG.md) and reports spelling errors (if any exist). Hook is placed after file format checks but before code linting hooks in `.pre-commit-config.yaml`. Hook uses official cspell-pre-commit repository
  - 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
  - [~] 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: Create a test markdown file with intentional spelling error (e.g., "teh" instead of "the"). Attempt to commit the file: `git add test.md && git commit -m "test: add file with spelling error"`. Commit fails with cspell error message showing the misspelled word and suggestions. Error output clearly indicates which file contains spelling errors and which words are misspelled
  - Proof Artifact(s): Git commit failure output showing cspell error, cspell error message with spelling suggestions displayed, test markdown file with intentional error
  - [ ] 3.1 Create a temporary test markdown file `test-spell-check.md` with intentional spelling errors (e.g., "teh" instead of "the", "recieve" 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: `CONTRIBUTING.md` includes new "Spell Checking" section explaining the cspell hook, how to add new terms to the dictionary, and how to verify spell checking works. Documentation follows existing CONTRIBUTING.md structure and style. Running `pre-commit run cspell --all-files` confirms all existing markdown files pass spell checking after dictionary configuration
  - Proof Artifact(s): Updated `CONTRIBUTING.md` with spell checking section, all existing markdown files pass spell checking (no false positives)
  - [ ] 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

fail_fast: false
default_install_hook_types: [pre-commit, pre-push, commit-msg]
default_stages: [pre-commit]

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-json
      - id: check-toml
      - id: check-merge-conflict
      - id: debug-statements
      - id: mixed-line-ending
  - repo: https://github.com/streetsidesoftware/cspell-pre-commit
    rev: v0.1.0
    hooks:
      - id: cspell
        files: \.md$
        exclude: CHANGELOG\.md
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.3
    hooks:
      - id: ruff-check
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format

  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.45.0
    hooks:
      - id: markdownlint-fix
        exclude: "CHANGELOG.md|LICENSE"

  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
    rev: v9.23.0
    hooks:
      - id: commitlint
        name: lint commit message for Conventional Commits compliance
        additional_dependencies: ['@commitlint/config-conventional']
        stages: [commit-msg]
        args:
          - "--extends=@commitlint/config-conventional"

  - repo: local
    hooks:
    - id: run-tests
      name: Run pytest before push
      entry: pytest
      language: system
      stages: [pre-push]
      pass_filenames: false
      always_run: true

fail_fast: false
default_install_hook_types: [pre-commit, pre-push, commit-msg]
default_stages: [pre-commit]

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-json
      - id: check-toml
      - id: check-merge-conflict
      - id: debug-statements
      - id: mixed-line-ending
  - repo: local
    hooks:
      - id: cspell
        name: cspell
        entry: cspell
        language: system
        types: [text]
        files: \.md$
        exclude: CHANGELOG\.md
        args: [--config, .cspell.json]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.14.3
    hooks:
      - id: ruff-check
        args: [--fix, --exit-non-zero-on-fix]
      - id: ruff-format

  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.45.0
    hooks:
      - id: markdownlint-fix
        exclude: "CHANGELOG.md|LICENSE"

  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
    rev: v9.23.0
    hooks:
      - id: commitlint
        name: lint commit message for Conventional Commits compliance
        additional_dependencies: ['@commitlint/config-conventional']
        stages: [commit-msg]
        args:
          - "--extends=@commitlint/config-conventional"

  - repo: local
    hooks:
    - id: run-tests
      name: Run pytest before push
      entry: pytest
      language: system
      stages: [pre-push]
      pass_filenames: false
      always_run: true

{
  "version": "0.2",
  "language": "en",
  "files": ["**/*.md"],
  "ignorePaths": [
    "CHANGELOG.md",
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**",
    "htmlcov/**"
  ],
  "words": [
    "Liatrio",
    "slash-man",
    "SDD",
    "MCP",
    "spec-driven",
    "liatrio-labs",
    "pytest",
    "ruff",
    "typer",
    "fastmcp",
    "questionary",
    "uvx",
    "uv",
    "pyyaml",
    "tomli",
    "hatchling",
    "semantic-release",
    "commitlint",
    "markdownlint",
    "GitHub",
    "Python",
    "JSON",
    "YAML",
    "CLI",
    "MCP",
    "HTTP",
    "STDIO",
    "PyPI",
    "CI",
    "CD",
    "API",
    "htmlcov",
    "frontmatter",
    "pyproject",
    "Demoable",
    "demoable",
    "Chainguard",
    "scriptable",
    "octo",
  ],
  "flagWords": [],
  "ignoreRegExpList": [
    "/```[\\s\\S]*?```/g",
    "/https?:\\/\\/[^\\s]+/g",
    "/[\\/\\\\][^\\s]+/g",
    "/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g"
  ]
}

  - [x] 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)
  - [x] 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)
  - [x] 2.3 Configure hook to check only markdown files by adding `files: \.md$` pattern or using appropriate file filtering
  - [x] 2.4 Configure hook to exclude `CHANGELOG.md` using `exclude: CHANGELOG\.md` pattern (matching markdownlint exclusion pattern)
  - [x] 2.5 Verify hook placement in config file: cspell hook should appear after `check-toml` hook and before `ruff-check` hook
  - [x] 2.6 Test hook installation by running `pre-commit install` (or verify it's already installed)
  - [x] 2.7 Test hook execution by running `pre-commit run cspell --all-files` and verify it checks markdown files successfully
  - [x] 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

    "API",
    "REST",
    "htmlcov",
    "frontmatter",
    "pyproject",
    "Demoable",
    "demoable",
    "Chainguard",
    "scriptable",
    "octo"

{
  "version": "0.2",
  "language": "en",
  "files": ["**/*.md"],
  "ignorePaths": [
    "CHANGELOG.md",
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**",
    "htmlcov/**"
  ],
  "words": [
    "Liatrio",
    "slash-man",
    "SDD",
    "MCP",
    "spec-driven",
    "liatrio-labs",
    "pytest",
    "ruff",
    "typer",
    "fastmcp",
    "questionary",
    "uvx",
    "uv",
    "pyyaml",
    "tomli",
    "hatchling",
    "semantic-release",
    "commitlint",
    "markdownlint",
    "GitHub",
    "Python",
    "JSON",
    "YAML",
    "CLI",
    "MCP",
    "HTTP",
    "STDIO",
    "PyPI",
    "CI",
    "CD",
    "API",
    "htmlcov",
    "frontmatter",
    "pyproject",
    "Demoable",
    "demoable",
    "Chainguard",
    "scriptable",
    "octo"
  ],
  "flagWords": [],
  "ignoreRegExpList": [
    "/```[\\s\\S]*?```/g",
    "/https?:\\/\\/[^\\s]+/g",
    "/[\\/\\\\][^\\s]+/g",
    "/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}/g"
  ]
}