diff --git a/.github/prompts/experimental/cspell-config.prompt.md b/.github/prompts/experimental/cspell-config.prompt.md new file mode 100644 index 000000000..9760c2628 --- /dev/null +++ b/.github/prompts/experimental/cspell-config.prompt.md @@ -0,0 +1,80 @@ +--- +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 (long random hashes, base64 strings, generated identifiers). +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. +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 more than 50 issues remain, 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 significantly reduced issue count (ideally fewer than 50). When not achievable automatically, provide a prioritized list of remaining tokens and typos for manual review. + +## 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. +* 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. diff --git a/collections/experimental.collection.md b/collections/experimental.collection.md index 48f4d2feb..dd0637f0b 100644 --- a/collections/experimental.collection.md +++ b/collections/experimental.collection.md @@ -10,6 +10,12 @@ Experimental and preview artifacts not yet promoted to stable collections. Items | **pptx** | Creates, updates, and manages PowerPoint slide decks using YAML-driven content with python-pptx | | **pptx-subagent** | Executes PowerPoint skill operations including content extraction, YAML creation, deck building, and visual validation | +### Prompts + +| Name | Description | +|-------------------|---------------------------------------------------------------------------------------------| +| **cspell-config** | Creates or updates the project cspell configuration with project-specific words and ignores | + ### Instructions | Name | Description | diff --git a/collections/experimental.collection.yml b/collections/experimental.collection.yml index eba69bc46..fa3e6c2c9 100644 --- a/collections/experimental.collection.yml +++ b/collections/experimental.collection.yml @@ -22,6 +22,10 @@ items: kind: skill - path: .github/skills/experimental/vscode-playwright kind: skill + # Prompts + - path: .github/prompts/experimental/cspell-config.prompt.md + kind: prompt + maturity: experimental # Instructions - path: .github/instructions/experimental/experiment-designer.instructions.md kind: instruction diff --git a/collections/hve-core-all.collection.md b/collections/hve-core-all.collection.md index ce848da12..88c5e16fa 100644 --- a/collections/hve-core-all.collection.md +++ b/collections/hve-core-all.collection.md @@ -82,6 +82,7 @@ Use this edition when you want access to everything without choosing a focused c | **checkpoint** | Save or restore conversation context using memory files | | **code-review-full** | Run both functional and standards code reviews on the current branch in a single pass | | **code-review-functional** | Pre-PR branch diff review for functional correctness, error handling, edge cases, and testing gaps | +| **cspell-config** | Creates or updates the project cspell configuration with project-specific words and ignores | | **doc-ops-update** | Invoke doc-ops agent for documentation quality assurance and updates | | **dt-canonical-deck** | Unified canonical deck workflow for opt-in offer, snapshot generation/refresh, and optional customer-card PowerPoint build | | **dt-figma-export** | Export Design Thinking artifacts to a collaborative FigJam board or Figma Design file using the official Figma MCP server | diff --git a/collections/hve-core-all.collection.yml b/collections/hve-core-all.collection.yml index eb93015a8..7d3db14c2 100644 --- a/collections/hve-core-all.collection.yml +++ b/collections/hve-core-all.collection.yml @@ -199,6 +199,9 @@ items: - path: .github/prompts/design-thinking/dt-start-project.prompt.md kind: prompt maturity: preview +- path: .github/prompts/experimental/cspell-config.prompt.md + kind: prompt + maturity: experimental - path: .github/prompts/github/github-add-issue.prompt.md kind: prompt - path: .github/prompts/github/github-discover-issues.prompt.md diff --git a/plugins/experimental/.github/plugin/plugin.json b/plugins/experimental/.github/plugin/plugin.json index 87d28001a..4d3c35e4f 100644 --- a/plugins/experimental/.github/plugin/plugin.json +++ b/plugins/experimental/.github/plugin/plugin.json @@ -6,6 +6,9 @@ "agents/experimental/", "agents/experimental/subagents/" ], + "commands": [ + "commands/experimental/" + ], "skills": [ "skills/experimental/" ] diff --git a/plugins/experimental/README.md b/plugins/experimental/README.md index 42c50be35..893543ed8 100644 --- a/plugins/experimental/README.md +++ b/plugins/experimental/README.md @@ -19,6 +19,12 @@ Experimental and preview artifacts not yet promoted to stable collections. Items | **pptx** | Creates, updates, and manages PowerPoint slide decks using YAML-driven content with python-pptx | | **pptx-subagent** | Executes PowerPoint skill operations including content extraction, YAML creation, deck building, and visual validation | +### Prompts + +| Name | Description | +|-------------------|---------------------------------------------------------------------------------------------| +| **cspell-config** | Creates or updates the project cspell configuration with project-specific words and ignores | + ### Instructions | Name | Description | @@ -52,6 +58,12 @@ copilot plugin install experimental@hve-core | pptx | Creates, updates, and manages PowerPoint slide decks using YAML-driven content with python-pptx | | pptx-subagent | Executes PowerPoint skill operations including content extraction, YAML creation, deck building, and visual validation | +## Commands + +| Command | Description | +|---------------|---------------------------------------------------------------------------------------------| +| cspell-config | Creates or updates the project cspell configuration with project-specific words and ignores | + ## Instructions | Instruction | Description | diff --git a/plugins/experimental/commands/experimental/cspell-config.md b/plugins/experimental/commands/experimental/cspell-config.md new file mode 120000 index 000000000..9fa942644 --- /dev/null +++ b/plugins/experimental/commands/experimental/cspell-config.md @@ -0,0 +1 @@ +../../../../.github/prompts/experimental/cspell-config.prompt.md \ No newline at end of file diff --git a/plugins/hve-core-all/.github/plugin/plugin.json b/plugins/hve-core-all/.github/plugin/plugin.json index 78efc00b6..1d160455a 100644 --- a/plugins/hve-core-all/.github/plugin/plugin.json +++ b/plugins/hve-core-all/.github/plugin/plugin.json @@ -23,6 +23,7 @@ "commands/coding-standards/", "commands/data-science/", "commands/design-thinking/", + "commands/experimental/", "commands/github/", "commands/hve-core/", "commands/jira/", diff --git a/plugins/hve-core-all/README.md b/plugins/hve-core-all/README.md index c11f5efd7..97182caf0 100644 --- a/plugins/hve-core-all/README.md +++ b/plugins/hve-core-all/README.md @@ -89,6 +89,7 @@ Use this edition when you want access to everything without choosing a focused c | **checkpoint** | Save or restore conversation context using memory files | | **code-review-full** | Run both functional and standards code reviews on the current branch in a single pass | | **code-review-functional** | Pre-PR branch diff review for functional correctness, error handling, edge cases, and testing gaps | +| **cspell-config** | Creates or updates the project cspell configuration with project-specific words and ignores | | **doc-ops-update** | Invoke doc-ops agent for documentation quality assurance and updates | | **dt-canonical-deck** | Unified canonical deck workflow for opt-in offer, snapshot generation/refresh, and optional customer-card PowerPoint build | | **dt-figma-export** | Export Design Thinking artifacts to a collaborative FigJam board or Figma Design file using the official Figma MCP server | @@ -376,6 +377,7 @@ copilot plugin install hve-core-all@hve-core | dt-method-next | Assess DT project state and recommend next method with sequencing validation - Brought to you by microsoft/hve-core | | dt-resume-coaching | Resume a Design Thinking coaching session — reads coaching state and re-establishes context - Brought to you by microsoft/hve-core | | dt-start-project | Start a new Design Thinking coaching project with state initialization and first coaching interaction - Brought to you by microsoft/hve-core | +| cspell-config | Creates or updates the project cspell configuration with project-specific words and ignores | | github-add-issue | Create a GitHub issue using discovered repository templates and conversational field collection | | github-discover-issues | Discover GitHub issues through user-centric queries, artifact-driven analysis, or search-based exploration and produce planning files for review | | github-execute-backlog | Execute a GitHub backlog plan by creating, updating, linking, closing, and commenting on issues from a handoff file | diff --git a/plugins/hve-core-all/commands/experimental/cspell-config.md b/plugins/hve-core-all/commands/experimental/cspell-config.md new file mode 120000 index 000000000..9fa942644 --- /dev/null +++ b/plugins/hve-core-all/commands/experimental/cspell-config.md @@ -0,0 +1 @@ +../../../../.github/prompts/experimental/cspell-config.prompt.md \ No newline at end of file