From Dev10x
Performs Dev10x plugin post-upgrade cleanup: updates version paths, migrates configs to canonical locations, ensures base permissions, merges worktree rules, generalizes session args, audits friction via permission-auditor, cleans redundant project rules. Use after version changes or persistent permission prompts.
npx claudepluginhub dev10x-guru/dev10x-claude --plugin Dev10xThis skill is limited to using the following tools:
**Announce:** "Using upgrade-cleanup to maintain Claude Code
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Announce: "Using upgrade-cleanup to maintain Claude Code permission settings and migrate config files across all projects."
This skill follows references/task-orchestration.md patterns.
Auto-advance: Complete each step, immediately start the next. Run dry-run first, then apply — no pause between steps.
REQUIRED: Create tasks before ANY work. Execute these
TaskCreate calls at startup:
TaskCreate(subject="Update version paths", activeForm="Updating paths")TaskCreate(subject="Migrate config files", activeForm="Migrating configs")TaskCreate(subject="Ensure base permissions", activeForm="Ensuring base perms")TaskCreate(subject="Generalize session-specific permissions", activeForm="Generalizing perms")
4b. TaskCreate(subject="Enumerate MCP tool globs", activeForm="Enumerating MCP globs")TaskCreate(subject="Ensure script coverage", activeForm="Verifying script rules")TaskCreate(subject="Merge worktree permissions", activeForm="Merging worktree perms")TaskCreate(subject="Audit permissions for friction", activeForm="Auditing permissions")TaskCreate(subject="Clean project files", activeForm="Cleaning project files")Set sequential dependencies. Mark each step in_progress when
starting and completed when done. Steps that produce no
changes (dry-run shows no diff) should still be marked
completed with a note in the description.
Bash() allow rules fail because paths reference an old versionclaude plugin updateInitialize userspace config with your project roots:
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/update-paths.py --init
Then edit ~/.claude/skills/Dev10x:upgrade-cleanup/projects.yaml
to add your project roots.
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/update-paths.py --dry-run
For large updates (many settings files), prefer --summary to
get one line per changed file instead of full per-file detail:
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/update-paths.py --dry-run --summary
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/update-paths.py
Move config files from deprecated locations to canonical Dev10x paths. Files are moved (not copied) so old paths stop working immediately.
Migrations:
| Old path | New path |
|---|---|
~/.claude/memory/slack-config.yaml | ~/.claude/memory/Dev10x/slack-config.yaml |
~/.claude/memory/slack-config-code-review-requests.yaml | ~/.claude/memory/Dev10x/slack-config-code-review-requests.yaml |
~/.claude/memory/github-reviewers-config.yaml | ~/.claude/memory/Dev10x/github-reviewers-config.yaml |
~/.claude/memory/databases.yaml | ~/.claude/memory/Dev10x/databases.yaml |
For each file:
~/.claude/memory/Dev10x/ directory existsmv source to destinationSkip files that don't exist at the old path (user may not use that feature). Warn if a file exists at both old and new paths.
Add missing base permissions (gh CLI, /tmp/claude paths, git ops, MCP
tools, Dev10x config file RWE access) to all settings files. The base
set is defined in projects.yaml under base_permissions:.
Enumeration requirement: All script paths and MCP tool names
MUST be listed individually in base_permissions. Glob wildcards
(e.g., Bash(~/.claude/plugins/cache/**:*) or
mcp__plugin_Dev10x_*) cause permission friction — Claude Code
cannot pre-approve glob patterns for Bash or MCP tools, so each
invocation triggers a manual approval prompt. When adding new
scripts or MCP tools to the plugin, enumerate them explicitly in
projects.yaml following the existing per-script and per-tool
entries.
mcp__plugin_Dev10x_cli__update_paths(ensure_base=true, dry_run=true)
mcp__plugin_Dev10x_cli__update_paths(ensure_base=true)
Replace permission rules containing session-specific arguments (ticket IDs, PR numbers, temp file hashes) with generalized wildcard patterns that work across future sessions.
mcp__plugin_Dev10x_cli__update_paths(generalize=true, dry_run=true)
mcp__plugin_Dev10x_cli__update_paths(generalize=true)
What gets generalized:
detect-tracker.sh PAY-123 → detect-tracker.sh * (ticket IDs)gh-pr-detect.sh 42 → gh-pr-detect.sh * (PR numbers)gh-issue-get.sh 15 → gh-issue-get.sh * (issue numbers)generate-commit-list.sh 42 → generate-commit-list.sh * (PR args)/tmp/Dev10x/git/msg.AbCdEf.txt → /tmp/Dev10x/git/** (temp hashes)Claude Code does not expand mcp__plugin_Dev10x_* globs in allow
rules — glob-shaped MCP rules match nothing, so every MCP call
triggers a manual approval prompt. This step discovers Dev10x MCP
tools from the plugin's own server registrations and replaces any
matching wildcard in a settings file with the enumerated tool list.
Note: With
ensure_basealready auto-expanding stale MCP wildcards in step 3 (since v0.66.0), this step is usually a no-op. Run it to catch wildcards introduced by other tooling or external edits.
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/enumerate-mcp.py --dry-run
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/enumerate-mcp.py
What gets expanded:
mcp__plugin_Dev10x_* → every tool registered by the Dev10x
cli and db MCP servers (deduplicated against existing rules)mcp__plugin_Dev10x_cli_* → every tool registered by the Dev10x
cli server onlyThe catalog is auto-discovered by parsing @server.tool()
decorators in src/dev10x/mcp/server_cli.py and server_db.py,
so the expansion is always accurate for the plugin version you
have checked out.
Verify that all callable scripts in the current plugin version have individual allow rules in each settings file. New plugin versions may add scripts that are not yet enumerated.
mcp__plugin_Dev10x_cli__update_paths(ensure_scripts=true, dry_run=true)
mcp__plugin_Dev10x_cli__update_paths(ensure_scripts=true)
What gets scanned:
bin/*.sh — helper scriptshooks/scripts/*.py, hooks/scripts/*.sh — hook implementationsskills/*/scripts/*.py, skills/*/scripts/*.sh — skill scriptsWorktrees accumulate allow rules during sessions that the main project never sees. This script collects stable permissions from all worktrees and merges them back.
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/merge-worktree-permissions.py --dry-run
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/merge-worktree-permissions.py
Session-specific noise (temp file hashes, inline conditionals, ticket- specific script args) is filtered out automatically. Only stable, reusable permissions are merged.
Dispatch the permission-auditor agent to perform a comprehensive
7-phase security and friction audit. The agent analyzes:
Invoke: Launch the permission-auditor agent via:
Agent(subagent_type="Dev10x:permission-auditor",
description="Audit permission settings",
prompt="Audit all Claude Code permission settings for security
gaps, overly broad rules, and friction-causing patterns.
Pay special attention to allow rules that permit direct script
calls when equivalent skills exist — these cause friction and
should be replaced with Skill() invocations or blocked.")
The agent produces a severity-categorized report with specific fix proposals. Review and apply selectively.
Strip redundant rules from project settings.local.json files that are
now covered by global ~/.claude/settings.json. Also flags rules
containing leaked secrets (env vars with plaintext credential values).
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/clean-project-files.py --dry-run
For large cleanups, prefer --summary to get one line per
changed file instead of full per-file detail. (Files with
flagged secrets always show full output regardless of mode.)
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/clean-project-files.py --dry-run --summary
${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/scripts/clean-project-files.py
What gets cleaned:
GIT_SEQUENCE_EDITOR=*, DATABASE_URL=*, etc.)do, done, fi, for, while, etc.)Read(//work/...))Leaked secret detection: Rules containing plaintext credentials
(e.g., LINEAR_KEY=lin_api_...) are flagged with warnings so users
know they were persisted in settings files and can rotate them.
The script looks for projects.yaml in two locations (first wins):
~/.claude/skills/Dev10x:upgrade-cleanup/projects.yaml (userspace)${CLAUDE_PLUGIN_ROOT}/skills/upgrade-cleanup/projects.yaml (plugin default)The userspace config is user-specific and not tracked in git. The plugin default ships with empty roots as a template.
| Parameter | Purpose |
|---|---|
dry_run | Preview changes without writing |
version | Target a specific version instead of latest |
init | Copy plugin default config to userspace for customization |
ensure_base | Add missing base permissions from projects.yaml |
generalize | Replace session-specific args with wildcard patterns |
ensure_scripts | Verify all plugin scripts have allow rules; add missing |
| Flag | Purpose |
|---|---|
--dry-run | Preview what would change without writing |
--summary | One line per changed file (count) — concise output |
--quiet | Suppress per-file details and headers |
--version VER | Target a specific version instead of latest |
--restore | Restore settings from most recent backups |
| Flag | Purpose |
|---|---|
--dry-run | Preview what would be merged without writing |
| Flag | Purpose |
|---|---|
--dry-run | Preview what would be cleaned without writing |
--summary | One line per changed file (count) — concise output |
--verbose | Print every affected rule (verbose) |