---
agent: "agent"
description: "Creates or updates the project cspell configuration with project-specific words and ignores"
---

# Update cspell configuration with project-specific words and ignores

## Context

* Goal: Add commonly used project-specific words to the cspell configuration, alphabetize the words list, and add useful `ignorePaths` aligned with the project's ignore files.
* cspell supports multiple config formats and file names. The agent must detect which format the project uses rather than assuming any specific one.
* Projects may also use custom dictionary files (`.txt` word lists) organized in a dedicated directory. The agent must discover and respect existing dictionary structure.

## Required Steps

### Step 1: Detect project context

1. Identify the project's primary language and package manager by inspecting files at the workspace root (e.g., `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `pom.xml`, `Gemfile`).
2. Determine how cspell is installed or available. Check for: a project dependency (npm, pip, or equivalent), a global install (`cspell --version`), or `npx`/`npx`-equivalent availability. If cspell is not available, ask the user for their preferred installation method.
3. Check for an existing spell-check script in the project's task runner (e.g., `package.json` scripts, `Makefile` targets, `justfile` recipes, `pyproject.toml` scripts). Use the project command when one exists.

### Step 2: Detect cspell configuration

1. Search the workspace root for any cspell config file using a broad glob pattern (e.g., `cspell*`, `.cspell*`). cspell recognizes many naming variants including dotfiles (`.cspell.json`), plain names (`cspell.json`), JSONC (`cspell.jsonc`), JS modules (`cspell.config.{js,cjs,mjs}`), and YAML (`cspell.config.{yaml,yml}`). Also check `package.json` for a `cspell` configuration key.
2. If multiple config files exist, use the first match and note the others for the user.
3. If no config file exists, create `cspell.json` with a minimal scaffold (`version`, `language`, `ignorePaths`, `words`).
4. Record the detected config path and format (JSON, YAML, or JS module) for subsequent steps.

### Step 3: Detect custom dictionaries

1. Search for a `.cspell/` directory or any path referenced in the config's `dictionaryDefinitions` field.
2. Catalog existing custom dictionary text files (`.txt` word lists) and note their names, paths, and apparent categories.
3. Check the `dictionaries` field for enabled built-in dictionaries (e.g., `k8s`, `docker`, `rust`, `aws`, `terraform`, `python`, `csharp`).
4. When adding new words later, route each token to either the inline `words` array or an existing custom dictionary file based on category fit. If no custom dictionaries exist, add all tokens to the inline `words` array.

### Step 4: Run initial spell check

1. Run cspell using the project command discovered in Step 1, or fall back to direct invocation (e.g., `npx cspell "**/*"`, `cspell "**/*"`).
2. Collect unknown words from the output, excluding paths already covered by `ignorePaths`.

### Step 5: Curate and categorize tokens

1. Group unknown tokens into categories: project-specific terms, acronyms, technology names, environment variables, proper nouns, and potential typos.
2. Filter out obvious garbage using these heuristics:
   * Hex strings of 16+ characters (`[a-f0-9]{16,}`)
   * Base64 looking strings (`[A-Za-z0-9+/]{20,}={0,2}`)
   * Tokens appearing only in lockfiles, minified assets, or build output
3. Identify likely typos that should be fixed in source rather than added to the dictionary (e.g., `recieve` → `receive`). Report these separately for the user to review. <!-- cspell:disable-line -->
4. For each remaining token, decide placement: inline `words` array for project-specific terms, or the appropriate custom dictionary file when one exists and the token fits its category.

### Step 6: Update configuration and dictionaries

1. Add curated tokens to the `words` array or the appropriate custom dictionary file. Preserve original casing and avoid introducing duplicates.
2. Sort the `words` array alphabetically (case-insensitive sort, preserve original case).
3. Sort custom dictionary text files alphabetically with one word per line if they follow that convention.
4. Add or refine `ignorePaths` entries to align with the project's ignore files (`.gitignore`, `.dockerignore`, etc.), but do not ignore source folders containing meaningful code and documentation.
5. Preserve the existing config format and style conventions (indentation, trailing commas, module export structure).

### Step 7: Validate and report

1. Re-run cspell using the same command from Step 4.
2. Report the final counts: files checked, issues found, files with issues.
3. If the issue count has not meaningfully decreased from baseline (target: ≥80% reduction), provide a short rationale and suggest next actions (add more words, fix typos, or add more ignore paths).
4. List any typos identified in Step 5 that should be fixed in source.

## Acceptance criteria

* The cspell configuration includes a comprehensive `ignorePaths` array that excludes generated and vendored folders.
* The `words` array and any custom dictionary files contain the most common project-specific tokens, alphabetized and deduplicated.
* A final cspell run shows a meaningful reduction from the baseline (target ≥80%, or the agent documents the remaining categories with rationale).

## Notes and best practices

* Preserve original casing for tokens (do not normalize to uppercase or lowercase).
* Prefer adding tokens for environment variables, infrastructure outputs, and technology names rather than silencing real typos.
* When in doubt about a token that appears only once in generated files, prefer ignoring the generated file path instead of adding the token.
* For diacritics and special characters (e.g., `Piña`, `José`, `Müller`, `Straße`, `naïve`, `résumé`, `Zürich`), preserve the original forms but consider adding simplified fallbacks only if tests or files use them. <!-- cspell:disable-line -->
* When the project uses a JS/CJS/MJS config format, preserve the module export structure and do not convert to JSON.
* Adapt file-type globs for the spell-check command to the project's languages (e.g., `"**/*.{py,md,yaml,yml}"` for Python projects, `"**/*.{cs,md,json}"` for C# projects).

---

Proceed with the Required Steps to detect, update, and validate the cspell configuration.