Add --update-cache option for Claude Code plugin development

[thschaffr]

Summary

This PR adds a --update-cache CLI option to the conversion script (src/convert_to_ide_formats.py) to streamline custom rule development for Claude Code environments. The flag is purely additive — it extends the existing converter; no other entry point or script is introduced.

Problem

When developing or customizing CodeGuard rules for Claude Code, users face workflow friction:

• Rules are generated to skills/software-security/ — The conversion script outputs Claude Code rules to the project's skills/ directory
• Claude Code reads from its plugin cache — The agent reads rules from ~/.claude/plugins/cache/project-codeguard/codeguard-security/{version}/skills/software-security/
• Manual sync required — Users must manually copy files to the cache directory for changes to take effect
• Version-specific paths — The cache path includes the version number, making manual updates error-prone

Solution

Extend the conversion script (src/convert_to_ide_formats.py) with an opt-in --update-cache flag that automatically syncs the just-generated rules to Claude Code's local plugin cache directory at the end of a successful conversion run. Off by default — no impact on standard CI builds or contributor workflow when the flag is not passed.

Changes

All changes are scoped to src/convert_to_ide_formats.py (the existing conversion script). No new scripts, modules, or dependencies are introduced.

• Add update_claude_cache(version) function to src/convert_to_ide_formats.py to sync rules to the Claude Code plugin cache
• Add --update-cache CLI flag to the same script's argparse setup, triggering the sync after a successful conversion
• Cache path is version-aware: the version is read from pyproject.toml via the existing get_version_from_pyproject() helper and passed through to update_claude_cache()
• Marketplace name (project-codeguard) and plugin name (codeguard-security) are pinned in the function to match .claude-plugin/marketplace.json and .claude-plugin/plugin.json
• Validate version against [A-Za-z0-9._-]+ allow-list before splicing into a filesystem path (defense-in-depth against path traversal)
• Fully replace the existing version directory (rmtree of cache_base, then copytree) so stale rules from a previous build can't linger. Note: this is not atomic — there is a brief window where the cache directory is missing or partially written; the flag is intended for dev use where this is acceptable
• Wrap all shutil operations in try/except; failures exit non-zero with a clear message
• Verify rules and SKILL.md were actually copied before returning success

No new dependencies; only stdlib (re, shutil, pathlib).

Usage

# Convert core rules and update Claude Code cache
python src/convert_to_ide_formats.py --update-cache

# Combine with tag filter (cache will then contain only the filtered subset)
python src/convert_to_ide_formats.py --tag authentication --update-cache

# Convert multiple source directories and update cache
python src/convert_to_ide_formats.py --source core custom --update-cache

Note: The --source flag accepts multiple directories under sources/rules/. In the last example, custom refers to a hypothetical sources/rules/custom/ directory — this does not exist by default in the repository. Users can create their own source directories (e.g., sources/rules/internal/) to organize organization-specific rules alongside the core rules.

Use Cases

• Developing custom rules for internal/organization use
• Testing rule modifications before contributing upstream
• Rapid iteration on rule content without manual file copying
• Debugging skill behavior after changes to agentskills.py or the SKILL.md template

Test Plan

• Run conversion with --update-cache flag
• Verify rules are copied to ~/.claude/plugins/cache/project-codeguard/codeguard-security/{version}/skills/software-security/ (tested with isolated $HOME: 23 rules + SKILL.md copied)
• Test with invalid version format to verify validation rejects before any FS write
• Verify the version cache directory is cleared and rewritten on each run (no stale files linger)
• Verify standard build is unaffected when flag is omitted
• Verify --help documents the new flag clearly

[thomas-bartlett]

Thank you for looking into this.

While reviewing, I noticed Claude Code has a flag for this. From the plugin docs: "Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation."

Since this repo is already a plugin (.claude-plugin/plugin.json + skills/), the dev loop can be:

uv run python src/convert_to_ide_formats.py
claude --plugin-dir .

I tested it locally and edits to SKILL.md show up in the next --plugin-dir session. This avoids copying directly into Claude Code’s cache. Maybe we should document this in CONTRIBUTING.md so the workflow is easier to find. What do you think?

[thschaffr]

Thank you for looking into this.

While reviewing, I noticed Claude Code has a flag for this. From the plugin docs: "Use the --plugin-dir flag to test plugins during development. This loads your plugin directly without requiring installation."

Since this repo is already a plugin (.claude-plugin/plugin.json + skills/), the dev loop can be:

uv run python src/convert_to_ide_formats.py
claude --plugin-dir .

I tested it locally and edits to SKILL.md show up in the next --plugin-dir session. This avoids copying directly into Claude Code’s cache. Maybe we should document this in CONTRIBUTING.md so the workflow is easier to find. What do you think?

Hi Thomas,

I will look into this. I remember having issues with ClaudeCode running in e.g. VSCode not being able to see new custom rule files. I saw that the model always referenced the cached version which was outdated. Therefore, I think it might not "just" be related to the SKILL.md file. I will double check it and get back to you.

Thank you.