From 0bbcac1240d8445668202f73b919508e82b52709 Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:36:51 -0500 Subject: [PATCH 1/5] =?UTF-8?q?=E2=9C=A8=20Add=20/ai-coding-config=20docto?= =?UTF-8?q?r=20diagnostic=20subcommand?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends /ai-coding-config with a doctor mode that runs a battery of health checks and reports as a ✅/⚠️/❌ checklist: - Plugin install state (marketplace registered, cache present, enabled) - Symlink integrity (.claude/commands → plugins/core/*, rules/ → .cursor/rules/) - Hook script health (executable, valid shebang, registered in settings) - Settings JSON validity - Marketplace JSON consistency (version parity across all three locations) - Version drift (local command file vs source repo) - Skill frontmatter (name/description/triggers present, next-skill targets exist) Context-aware: detects source-repo vs user-project and skips inapplicable checks. Auto-fixes hook permissions only (with confirmation). All other issues report with suggested fix commands. Fixes #53 Co-Authored-By: Claude Opus 4.7 --- plugins/core/commands/ai-coding-config.md | 184 +++++++++++++++++++++- 1 file changed, 182 insertions(+), 2 deletions(-) diff --git a/plugins/core/commands/ai-coding-config.md b/plugins/core/commands/ai-coding-config.md index 0cc112d..490f9cf 100644 --- a/plugins/core/commands/ai-coding-config.md +++ b/plugins/core/commands/ai-coding-config.md @@ -1,8 +1,8 @@ --- # prettier-ignore description: "Set up or update AI coding configurations - interactive setup for Claude Code, Cursor, and other AI coding tools" -argument-hint: "[update]" -version: 4.1.1 +argument-hint: "[update|doctor]" +version: 4.2.0 --- # AI Coding Configuration @@ -14,6 +14,7 @@ tools. The marketplace lives at `https://github.com/TechNickAI/ai-coding-config` - `/ai-coding-config` - Interactive setup for current project - `/ai-coding-config update` - Update plugins and configs to latest versions +- `/ai-coding-config doctor` - Diagnose plugin health, hook state, and config drift ## Interaction Guidelines @@ -524,6 +525,185 @@ If nothing changed (already up to date, no reset needed), skip the restart messa --- + + + +Run a diagnostic battery and report as a ✅ / ⚠️ / ❌ checklist. Group by category. +End with a suggested-fixes section. Read-only except for hook permission repair (safe, +reversible, no content change). Work conversationally — print results as you go rather +than collecting everything silently before reporting. + + + +Determine environment before running checks: + +- **Source repo**: `plugins/core/` directory exists at cwd. Run all checks including + symlink and plugin JSON consistency checks. +- **User project**: `plugins/core/` absent. Skip source-repo checks; focus on plugin + install state, settings, and hooks. + +Report which context was detected at the top of output. + + + + +### Plugin Install State + +Read `~/.claude/plugins/known_marketplaces.json` with the Read tool: +- ✅ ai-coding-config marketplace entry present +- ❌ Not found → suggest `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` + +Check `~/.claude/plugins/cache/ai-coding-config/` for plugin content using Glob: +- ✅ Cache directory exists with agents, commands, and skills subdirectories +- ❌ Cache missing or empty → suggest `/plugin install ai-coding-config` + +Read `~/.claude/settings.json` and check for plugin enablement: +- ✅ ai-coding-config appears in plugins/enabled list +- ⚠️ Not listed → plugin may be disabled; run `/plugin` to check status + +### Symlinks (source repo only) + +For each directory: `.claude/commands`, `.claude/agents`, `.claude/skills`: + +```bash +ls -la .claude/commands .claude/agents .claude/skills +``` + +- ✅ Each is a symlink pointing to the corresponding `plugins/core/` subdirectory +- ❌ Missing, not a symlink, or wrong target → note the broken symlink + +Check `rules/` → `.cursor/rules/`: + +```bash +ls -la rules +``` + +- ✅ `rules` is a symlink to `.cursor/rules` +- ❌ Missing or wrong → `ln -s .cursor/rules rules` + +### Hook Scripts + +Read `plugins/core/hooks/hooks.json` to get declared hooks. For each hook script: + +```bash +ls -la plugins/core/hooks/*.sh +``` + +- ✅ File exists, executable (`-x`), and first line is `#!/bin/bash` +- ⚠️ Exists but not executable → offer to auto-fix: `chmod +x ` +- ❌ File missing → note as broken + +Check that hooks are registered in project or global settings: + +```bash +cat .claude/settings.json 2>/dev/null | python3 -m json.tool > /dev/null && echo "valid" +``` + +- ✅ `settings.json` parses as valid JSON +- ❌ Invalid JSON → note the file and line (use `python3 -m json.tool` output) + +### Marketplace JSON Consistency (source repo only) + +Read both `.claude-plugin/marketplace.json` and `plugins/core/.claude-plugin/plugin.json`: +- ✅ Both parse as valid JSON +- ✅ `metadata.version` == `plugins[0].version` == `plugin.json version` +- ⚠️ Version mismatch → "Bump all three per `.claude-plugin/CLAUDE.md`" + +### Version Drift + +Compare installed command version vs source repo version. Read the `version` field from +the YAML frontmatter of: + +1. This command file (currently executing) +2. `~/.ai_coding_config/plugins/core/commands/ai-coding-config.md` (source, if it exists) + +- ✅ Versions match +- ⚠️ Source is newer → suggest `/ai-coding-config update` +- ⚠️ Source repo not found at `~/.ai_coding_config` → suggest cloning it + +### Skill Frontmatter + +Use Glob to list `plugins/core/skills/*/SKILL.md` (source repo) or +`~/.claude/plugins/cache/ai-coding-config/skills/*/SKILL.md` (user project). + +For each SKILL.md, read and verify: +- ✅ File has `---` YAML frontmatter block +- ✅ `name`, `description`, and `triggers` fields present +- ⚠️ Missing `triggers` → skill won't auto-activate on natural language +- If `next-skill` declared: ✅ that skill name exists in the skills directory or + `.claude/commands/` → ⚠️ if target not found + +Report a single summary line per skill (not per field) to keep output scannable. + + + + +Hook permissions are the only thing doctor auto-fixes (with user confirmation): + +"⚠️ verify-deliverables.sh is not executable. Fix now? [y/N]" + +If yes: `chmod +x plugins/core/hooks/verify-deliverables.sh` + +For all other issues, report and direct to the appropriate fix command. Don't modify +JSON files, settings, or symlinks without explicit user instruction. + + + +Print category headers as the checks complete. Example final output: + +``` +## ai-coding-config doctor + +Context: source repo (plugins/core/ detected) + +### Plugin Install State +✅ Marketplace registered (ai-coding-config v9.21.0) +✅ Plugin cache present +✅ Plugin enabled in settings + +### Symlinks +✅ .claude/commands → plugins/core/commands +✅ .claude/agents → plugins/core/agents +✅ .claude/skills → plugins/core/skills +❌ rules/ symlink missing + +### Hook Scripts +✅ verify-deliverables.sh — executable, valid shebang +⚠️ todo-persist.sh — exists but not executable + +### Marketplace JSON Consistency +✅ .claude-plugin/marketplace.json valid JSON +✅ plugins/core/.claude-plugin/plugin.json valid JSON +✅ Versions consistent (9.21.0) + +### Version Drift +✅ Command file up to date (v4.2.0) + +### Skill Frontmatter +✅ brainstorming — name, description, triggers, next-skill: brainstorm-synthesis (found) +✅ systematic-debugging — name, description, triggers, next-skill: verify-fix (found) +⚠️ mcp-debug — triggers field present, stability: experimental + +--- +## Summary +11 passed ✅ 1 warning ⚠️ 1 failure ❌ + +## Suggested Fixes +❌ rules/ symlink missing: + ln -s .cursor/rules rules + +⚠️ todo-persist.sh not executable: + chmod +x plugins/core/hooks/todo-persist.sh + (or confirm above to auto-fix) +``` + +Keep the summary tight. Users should be able to skim it in 10 seconds. + + + + +--- + Work conversationally, not robotically. Focus on outcomes. Determine best approach for each situation. Show file paths when copying. Let users make all choices. Verify everything works before finishing. From 23437d146e73cd0c7a1d72ba29f85eeadaa4412c Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:47:24 -0500 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=90=9B=20Fix=20five=20multi-review=20?= =?UTF-8?q?issues=20in=20ai-coding-config=20doctor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Source repo not found is informational (ℹ️), not a warning — normal for plugin-only users - Remove wrong user-project skill glob path (plugin cache uses flat .md, not SKILL.md dirs) - Fix summary count: 1 warning → 2 warnings in example output - Put failures first in summary line (❌ before ⚠️ before ✅) - Add all-green closing line to output-format guidance Co-Authored-By: Claude Sonnet 4.6 --- plugins/core/commands/ai-coding-config.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/plugins/core/commands/ai-coding-config.md b/plugins/core/commands/ai-coding-config.md index 490f9cf..6773a3d 100644 --- a/plugins/core/commands/ai-coding-config.md +++ b/plugins/core/commands/ai-coding-config.md @@ -530,8 +530,8 @@ If nothing changed (already up to date, no reset needed), skip the restart messa Run a diagnostic battery and report as a ✅ / ⚠️ / ❌ checklist. Group by category. End with a suggested-fixes section. Read-only except for hook permission repair (safe, -reversible, no content change). Work conversationally — print results as you go rather -than collecting everything silently before reporting. +reversible, no content change). Print each category header as you complete that group of +checks so the user sees progress — don't collect everything silently before reporting. @@ -596,11 +596,11 @@ ls -la plugins/core/hooks/*.sh Check that hooks are registered in project or global settings: ```bash -cat .claude/settings.json 2>/dev/null | python3 -m json.tool > /dev/null && echo "valid" +jq . .claude/settings.json > /dev/null 2>&1 && echo "valid" || echo "invalid" ``` - ✅ `settings.json` parses as valid JSON -- ❌ Invalid JSON → note the file and line (use `python3 -m json.tool` output) +- ❌ Invalid JSON → note the parse error from jq output ### Marketplace JSON Consistency (source repo only) @@ -619,12 +619,13 @@ the YAML frontmatter of: - ✅ Versions match - ⚠️ Source is newer → suggest `/ai-coding-config update` -- ⚠️ Source repo not found at `~/.ai_coding_config` → suggest cloning it +- ℹ️ Source repo not found at `~/.ai_coding_config` — normal for plugin-only users (no action needed) ### Skill Frontmatter -Use Glob to list `plugins/core/skills/*/SKILL.md` (source repo) or -`~/.claude/plugins/cache/ai-coding-config/skills/*/SKILL.md` (user project). +Use Glob to list `plugins/core/skills/*/SKILL.md` (source repo only — the plugin cache +uses flat `.md` files without subdirectories, so this check applies only in the source +repo context). For each SKILL.md, read and verify: - ✅ File has `---` YAML frontmatter block @@ -686,7 +687,7 @@ Context: source repo (plugins/core/ detected) --- ## Summary -11 passed ✅ 1 warning ⚠️ 1 failure ❌ +1 failure ❌ 2 warnings ⚠️ 11 passed ✅ ## Suggested Fixes ❌ rules/ symlink missing: @@ -697,6 +698,8 @@ Context: source repo (plugins/core/ detected) (or confirm above to auto-fix) ``` +All-green output ends with: "All checks passed — your setup is healthy." + Keep the summary tight. Users should be able to skim it in 10 seconds. From 5ecf04d082e62c89f0e07bc2a97a1948630a0a8a Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:48:39 -0500 Subject: [PATCH 3/5] =?UTF-8?q?=F0=9F=90=9B=20Address=20Claude=20bot=20rev?= =?UTF-8?q?iew=20on=20PR=20#56?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix auto-fix example to use todo-persist.sh (matches output-format example) - Replace relative ls -la bash examples with $(pwd)-anchored absolute paths and Glob/Read tool instructions, matching file's own best practices - Clarify next-skill resolution: directory name first (fast path), fall back to scanning name fields, also checks .claude/commands/ Co-Authored-By: Claude Sonnet 4.6 --- plugins/core/commands/ai-coding-config.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/plugins/core/commands/ai-coding-config.md b/plugins/core/commands/ai-coding-config.md index 6773a3d..9ed8fce 100644 --- a/plugins/core/commands/ai-coding-config.md +++ b/plugins/core/commands/ai-coding-config.md @@ -565,8 +565,10 @@ Read `~/.claude/settings.json` and check for plugin enablement: For each directory: `.claude/commands`, `.claude/agents`, `.claude/skills`: +Use Bash with absolute paths anchored to `$(pwd)`: + ```bash -ls -la .claude/commands .claude/agents .claude/skills +ls -la "$(pwd)/.claude/commands" "$(pwd)/.claude/agents" "$(pwd)/.claude/skills" ``` - ✅ Each is a symlink pointing to the corresponding `plugins/core/` subdirectory @@ -575,7 +577,7 @@ ls -la .claude/commands .claude/agents .claude/skills Check `rules/` → `.cursor/rules/`: ```bash -ls -la rules +ls -la "$(pwd)/rules" ``` - ✅ `rules` is a symlink to `.cursor/rules` @@ -583,11 +585,8 @@ ls -la rules ### Hook Scripts -Read `plugins/core/hooks/hooks.json` to get declared hooks. For each hook script: - -```bash -ls -la plugins/core/hooks/*.sh -``` +Read `plugins/core/hooks/hooks.json` with the Read tool to get declared hooks. Use Glob +to list `plugins/core/hooks/*.sh`, then check each file individually: - ✅ File exists, executable (`-x`), and first line is `#!/bin/bash` - ⚠️ Exists but not executable → offer to auto-fix: `chmod +x ` @@ -631,8 +630,10 @@ For each SKILL.md, read and verify: - ✅ File has `---` YAML frontmatter block - ✅ `name`, `description`, and `triggers` fields present - ⚠️ Missing `triggers` → skill won't auto-activate on natural language -- If `next-skill` declared: ✅ that skill name exists in the skills directory or - `.claude/commands/` → ⚠️ if target not found +- If `next-skill` declared: check by directory name first (fast path — the directory + name should match the skill name); if not found, fall back to scanning `name` fields + in each SKILL.md. Also check `.claude/commands/` for commands. ✅ target found, + ⚠️ target not found anywhere Report a single summary line per skill (not per field) to keep output scannable. @@ -641,9 +642,9 @@ Report a single summary line per skill (not per field) to keep output scannable. Hook permissions are the only thing doctor auto-fixes (with user confirmation): -"⚠️ verify-deliverables.sh is not executable. Fix now? [y/N]" +"⚠️ todo-persist.sh is not executable. Fix now? [y/N]" -If yes: `chmod +x plugins/core/hooks/verify-deliverables.sh` +If yes: `chmod +x plugins/core/hooks/todo-persist.sh` For all other issues, report and direct to the appropriate fix command. Don't modify JSON files, settings, or symlinks without explicit user instruction. From fa53a64f33f59e5725b9fa7500f484d871c853d0 Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 18:50:13 -0500 Subject: [PATCH 4/5] =?UTF-8?q?=F0=9F=90=9B=20Fix=20hook=20checks=20for=20?= =?UTF-8?q?user-project=20context=20and=20missing=20settings=20fallback?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Hook script file checks now scoped to source-repo only; user-project context checks hooks registration in settings instead of script files - auto-fix chmod also scoped to source-repo only context - Settings check now reads .claude/settings.json if present, falls back to ~/.claude/settings.json for projects using only global settings Co-Authored-By: Claude Sonnet 4.6 --- plugins/core/commands/ai-coding-config.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/plugins/core/commands/ai-coding-config.md b/plugins/core/commands/ai-coding-config.md index 9ed8fce..91abfbb 100644 --- a/plugins/core/commands/ai-coding-config.md +++ b/plugins/core/commands/ai-coding-config.md @@ -585,21 +585,23 @@ ls -la "$(pwd)/rules" ### Hook Scripts -Read `plugins/core/hooks/hooks.json` with the Read tool to get declared hooks. Use Glob -to list `plugins/core/hooks/*.sh`, then check each file individually: +**Source repo:** Read `plugins/core/hooks/hooks.json` with the Read tool to get +declared hooks. Use Glob to list `plugins/core/hooks/*.sh`, then check each file: - ✅ File exists, executable (`-x`), and first line is `#!/bin/bash` - ⚠️ Exists but not executable → offer to auto-fix: `chmod +x ` - ❌ File missing → note as broken -Check that hooks are registered in project or global settings: +**User project:** Hook script files are managed by the plugin cache — skip the script +file checks. Instead, verify hooks are registered in settings (see below). -```bash -jq . .claude/settings.json > /dev/null 2>&1 && echo "valid" || echo "invalid" -``` +Check that hooks are registered in project or global settings. Read `.claude/settings.json` +if it exists; otherwise fall back to `~/.claude/settings.json`: -- ✅ `settings.json` parses as valid JSON -- ❌ Invalid JSON → note the parse error from jq output +- ✅ Settings file parses as valid JSON and contains hook entries +- ⚠️ Valid JSON but no hooks registered → hooks won't fire; suggest running `/ai-coding-config update` +- ❌ Invalid JSON → note the parse error +- ℹ️ No local `.claude/settings.json` and global settings has no hooks → hooks rely on plugin marketplace loading ### Marketplace JSON Consistency (source repo only) @@ -640,7 +642,8 @@ Report a single summary line per skill (not per field) to keep output scannable. -Hook permissions are the only thing doctor auto-fixes (with user confirmation): +Hook permissions are the only thing doctor auto-fixes (with user confirmation), and +only in source-repo context where the script files are present: "⚠️ todo-persist.sh is not executable. Fix now? [y/N]" From 8201b12864db888c97ff63a010ca30fa67b0eb1b Mon Sep 17 00:00:00 2001 From: Nick Sullivan Date: Mon, 4 May 2026 19:35:03 -0500 Subject: [PATCH 5/5] =?UTF-8?q?=F0=9F=90=9B=20Address=20latest=20Claude=20?= =?UTF-8?q?bot=20review=20on=20PR=20#56?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add sync comment noting Plugin Install State mirrors - Add explicit file-not-found case for known_marketplaces.json - Add stability: experimental rule to Skill Frontmatter checks (was in example but not in spec) - Add Mode Routing section for unrecognized-argument fallback (enter setup mode, mention available subcommands) Co-Authored-By: Claude Sonnet 4.6 --- plugins/core/commands/ai-coding-config.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/plugins/core/commands/ai-coding-config.md b/plugins/core/commands/ai-coding-config.md index 91abfbb..e9df87f 100644 --- a/plugins/core/commands/ai-coding-config.md +++ b/plugins/core/commands/ai-coding-config.md @@ -16,6 +16,14 @@ tools. The marketplace lives at `https://github.com/TechNickAI/ai-coding-config` - `/ai-coding-config update` - Update plugins and configs to latest versions - `/ai-coding-config doctor` - Diagnose plugin health, hook state, and config drift +## Mode Routing + +- No argument → setup mode +- `update` → update mode +- `doctor` → doctor mode +- Unrecognized argument (typo, unknown subcommand) → setup mode; mention available + subcommands (`update`, `doctor`) at the start of output + ## Interaction Guidelines Use AskUserQuestion when presenting discrete choices that save the user time (selecting @@ -549,9 +557,13 @@ Report which context was detected at the top of output. ### Plugin Install State +These checks mirror the ones in `` (update-mode). If either section +is updated (e.g., a new settings key), keep both in sync. + Read `~/.claude/plugins/known_marketplaces.json` with the Read tool: - ✅ ai-coding-config marketplace entry present -- ❌ Not found → suggest `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` +- ❌ File not found → marketplace never initialized; suggest `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` +- ❌ File exists but ai-coding-config entry missing → suggest `/plugin marketplace add https://github.com/TechNickAI/ai-coding-config` Check `~/.claude/plugins/cache/ai-coding-config/` for plugin content using Glob: - ✅ Cache directory exists with agents, commands, and skills subdirectories @@ -636,6 +648,8 @@ For each SKILL.md, read and verify: name should match the skill name); if not found, fall back to scanning `name` fields in each SKILL.md. Also check `.claude/commands/` for commands. ✅ target found, ⚠️ target not found anywhere +- If `stability: experimental` declared: ℹ️ note as informational (expected for new or + actively-changing skills — not a problem, just surfaced for awareness) Report a single summary line per skill (not per field) to keep output scannable.