cc-thingz

Things to make Claude Code even better — hooks, skills, and commands, organized as a marketplace of independent plugins.

This is an unapologetically opinionated set. Every skill here is something I actually use — some multiple times a day (brainstorm, plan, review), others less often but worth having in the toolbox. There are plenty of plugin collections out there, from random grab-bags to well-organized catalogs. This one is mine, and it reflects how I work. Even if you don't need my particular toolbox, it might give you ideas for building your own and making Claude Code do what you want it to do.

Install

Add the marketplace, then install the plugins you want:

/plugin marketplace add umputun/cc-thingz

/plugin install brainstorm@umputun-cc-thingz
/plugin install review@umputun-cc-thingz
/plugin install planning@umputun-cc-thingz
/plugin install release-tools@umputun-cc-thingz
/plugin install thinking-tools@umputun-cc-thingz
/plugin install skill-eval@umputun-cc-thingz
/plugin install workflow@umputun-cc-thingz

Test a plugin locally:

claude --plugin-dir plugins/brainstorm

cp -r plugins/brainstorm/skills/brainstorm ~/.claude/skills/
cp -r plugins/brainstorm/scripts/ ~/.claude/skills/brainstorm/scripts
cp -r plugins/brainstorm/references/ ~/.claude/skills/brainstorm/references

cp -r plugins/review/skills/pr ~/.claude/skills/
cp -r plugins/review/skills/git-review ~/.claude/skills/
cp -r plugins/review/skills/writing-style ~/.claude/skills/
chmod +x ~/.claude/skills/git-review/scripts/git-review.py

cp plugins/planning/commands/make.md ~/.claude/commands/
cp -r plugins/planning/skills/exec ~/.claude/skills/
cp -r plugins/planning/scripts/ ~/.claude/commands/scripts
cp -r plugins/planning/references/ ~/.claude/commands/references
cp plugins/planning/scripts/plan-annotate.py ~/.claude/scripts/
chmod +x ~/.claude/scripts/plan-annotate.py
chmod +x ~/.claude/skills/exec/scripts/*.sh

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "ExitPlanMode",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/scripts/plan-annotate.py",
        "timeout": 345600
      }]
    }]
  }
}

cp -r plugins/release-tools/skills/new ~/.claude/skills/
cp -r plugins/release-tools/skills/last-tag ~/.claude/skills/
chmod +x ~/.claude/skills/new/scripts/*.sh

cp -r plugins/thinking-tools/skills/ask-codex ~/.claude/skills/
cp -r plugins/thinking-tools/skills/dialectic ~/.claude/skills/
cp -r plugins/thinking-tools/skills/root-cause-investigator ~/.claude/skills/

cp plugins/skill-eval/hooks/skill-forced-eval-hook.sh ~/.claude/scripts/
chmod +x ~/.claude/scripts/skill-forced-eval-hook.sh

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/scripts/skill-forced-eval-hook.sh"
      }]
    }]
  }
}

cp -r plugins/workflow/skills/learn ~/.claude/skills/
cp -r plugins/workflow/skills/clarify ~/.claude/skills/
cp -r plugins/workflow/skills/wrong ~/.claude/skills/
cp -r plugins/workflow/skills/md-copy ~/.claude/skills/
cp -r plugins/workflow/skills/txt-copy ~/.claude/skills/
cp -r plugins/workflow/skills/backlog ~/.claude/skills/

Updating plugins

The /plugin menu has two update paths, and they behave differently:

• /plugin → Marketplaces → Update marketplace — pulls the latest plugin catalog from the repo immediately. This is the reliable way to get updates.
• /plugin → Installed → Update now — uses a local cache that can be stale for a long time and may not reflect recent changes. Use this as a fallback after updating the marketplace.

To keep plugins current automatically, enable /plugin → Marketplaces → Enable auto-update. This updates the marketplace catalog on each session start.

Plugins

brainstorm

Collaborative design skill. Invoke with /brainstorm:do or trigger phrases like "brainstorm", "let's brainstorm", "help me design", "explore options for", etc.

Guides a 4-phase dialogue to turn ideas into designs:

1. Understand — gathers project context, asks questions one at a time (multiple choice preferred)
2. Explore Approaches — proposes 2-3 options with trade-offs, leads with recommendation
3. Present Design — breaks design into sections of 200-300 words, validates each incrementally
4. Next Steps — offers to write a plan (/planning:make), enter plan mode, or start implementing

review

PR review, interactive git diff annotation review, and writing style tools. Install together — review-pr uses writing-style for drafting comments.

review-pr — analyzes code quality, architecture, test coverage, and identifies scope creep:

• Phase 0 — detects PR vs issue (issues get a simpler comment-only flow)
• Phase 1 — fetches PR metadata, discussion history, merge status, and inline suggestions
• Phase 1.5 — asks review mode: Full (worktree + tests + linter + architecture) or Quick (diff-only)
• Phase 2 — sets up worktree and launches a subagent for deep analysis
• Phase 3-4 — presents findings, resolves open design questions
• Phase 5 — drafts review comment using /review:writing-style, posts as formal review
• Post-approve — recommends merge strategy (rebase vs squash vs merge)

Uses gh CLI for all GitHub operations and git worktrees to avoid disrupting the current checkout.

git-review — interactive annotation-based code review. Generates a cleaned-up diff, opens it in $EDITOR via agterm overlay, tmux popup, kitty overlay, or wezterm split-pane (agterm tried first). You annotate directly in the diff, and the script returns your changes as a git diff. Claude reads annotations, fixes code, regenerates the diff, and loops until you close the editor without changes. Supports auto-detection of uncommitted changes or branch diffs. Agterm users: needs agtermctl on PATH (bundled with agterm), no extra config; pane-scoped overlays need agterm 0.20.0+.

Run tests: python3 plugins/review/skills/git-review/scripts/git-review.py --test

writing-style — enforces direct, brief writing for tickets, PRs, code reviews, and commit messages. Core principles: brevity, honest feedback, problem-solution structure, technical precision, anti-AI-speak. Does NOT apply to README.md, public docs, or blog posts.

planning

Structured implementation planning with interactive annotation review and autonomous plan execution.

plan command — creates a plan file in docs/plans/yyyymmdd-<task-name>.md through interactive context gathering:

• Step 0 — parses intent and explores codebase for relevant context
• Step 1 — asks focused questions one at a time (goal, scope, constraints, testing approach, title)
• Step 1.5 — proposes 2-3 implementation approaches with trade-offs (skipped if obvious)
• Step 2 — creates the plan file with tasks, file lists, test requirements, and progress tracking
• Step 3 — offers interactive review (opens plan in $EDITOR via plan-annotate), auto review, start implementation, or done

plan-annotate.py — interactive plan annotation tool. Opens plans in your $EDITOR via a terminal overlay (agterm overlay, tmux popup, kitty overlay, or wezterm split-pane), lets you annotate directly, and feeds a unified diff back to Claude so it revises the plan. Two modes:

• Hook mode (default) — intercepts ExitPlanMode, opens plan in editor, denies tool call with diff if changes made, forcing revision loop
• File mode (plan-annotate.py <plan-file>) — outputs unified diff to stdout for integration with custom workflows

Requirements: agterm, tmux, kitty, or wezterm terminal (agterm tried first), $EDITOR (defaults to vi). Agterm users: needs agtermctl on PATH (bundled with agterm), no extra config; pane-scoped overlays need agterm 0.20.0+. Kitty users must enable remote control in kitty.conf:

allow_remote_control yes
listen_on unix:/tmp/kitty-$KITTY_PID

Note: when revdiff is installed, the ExitPlanMode hook and /planning:make interactive review both route through launch-plan-review.sh instead, which supports a wider set of overlays: agterm, tmux, zellij, herdr, orca, kitty, wezterm/kaku, cmux, ghostty, iTerm2, and emacs vterm. The 4-terminal list above applies only to the $EDITOR fallback when revdiff is not installed.

Disabling review: set PLANNING_DISABLE_REVDIFF=1 to skip interactive plan review entirely on both routes (revdiff and the $EDITOR fallback). No overlay opens and the plan proceeds to the normal ExitPlanMode confirmation. This exists for remote clients (claude /remote-control): the overlay always opens on the host terminal, which a mobile or web client cannot see or interact with, so review would otherwise block the session. The variable is read when review fires, so export it in your shell before starting a session you may later drive remotely.

The overlay popup size is configurable via env vars:

Run tests: python3 plugins/planning/scripts/plan-annotate.py --test

plan-review agent — automated plan quality reviewer. Analyzes plans for problem definition, solution correctness, scope creep, over-engineering, testing requirements, task granularity, and convention adherence. Used by the plan command's "Auto review" option. Outputs a structured report with severity-rated findings and an APPROVE/NEEDS REVISION verdict.

exec skill — autonomous plan executor. Takes a plan file (from /planning:make) and executes it task-by-task using isolated subagents. Execution phases:

1. Task loop — one subagent per task section, commits after each, retries on failure
2. Comprehensive review — 5 parallel agents (quality, implementation, testing, simplification, documentation) + fixer
3. Code smells — smells agent checks conventions, CLAUDE.md rules, code style + fixer
4. External review — always runs through run-external-review.sh: the configured external_review_cmd, or codex when that is unset. Adversarial loop with severity-aware early exit (stops after the first iteration that finds no critical/major issues; minor findings are still fixed). A tool that is not installed makes the phase skip; a tool that runs and exits non-zero, or exits 0 with no output, is reported as a reviewer failure rather than a clean review
5. Critical-only review — 2 agents (quality + implementation), critical/major issues only + fixer
6. Finalize — rebase, squash, verify (optional)
7. Stats summary — single agent reads the session log + git state and reports total tokens / wall-clock / per-phase breakdown / branch churn / fixer iterations
8. Completion — moves the finished plan into a completed/ subdirectory of its plans directory and commits the move (VCS-aware via move-plan.sh, no push), so completed plans leave the active plans directory and stop showing up as candidates on the next run; also reports every judgment call the run made on its own and any deviations from the plan

Review agents are read-only reporters. The fixer agent evaluates each finding, fixes confirmed issues, rejects false positives, and reports back.

Autonomous by design — the run assumes no human is available, so subagents never stop to ask questions. They resolve judgment calls the plan does not settle from the project's lint rules, CLAUDE.md, and surrounding code, log each decision and any plan deviation, and the orchestrator reports them all to you at completion. When the worktree option is chosen the entire run is isolated in a git worktree; the main working directory is never checked out to the feature branch or otherwise touched.

VCS support — the exec helper scripts are VCS-aware and work in both git and Mercurial (hg) repositories. The finalize and external-review phases remain git-only, but their behaviour can be customised for hg via .claude/exec-plan/prompts/finalizer.md and .claude/exec-plan/prompts/codex-review.md overrides.

Customization — prompts and agent definitions use a three-layer override chain (checked in order, first match wins):

1. Project: .claude/exec-plan/prompts/ and .claude/exec-plan/agents/
2. User: ${CLAUDE_PLUGIN_DATA}/prompts/ and ${CLAUDE_PLUGIN_DATA}/agents/
3. Bundled defaults (shipped with the plugin)

To customize, place your modified version in the override path. For example, to customize prompts/review.md at the project level:

.claude/exec-plan/prompts/review.md

Or at the user level (applies to all projects). To find <plugin-id>, run ls ~/.claude/plugins/data/ and look for the planning plugin entry:

~/.claude/plugins/data/<plugin-id>/prompts/review.md

Same pattern works for any prompt or agent file — just mirror the path under the override directory.

Nothing is copied into the override directories automatically. Installs before planning 3.10.0 did seed the user-level directory with copies of every bundled prompt and agent — those copies still shadow the bundled defaults and no longer track upgrades, so check ~/.claude/plugins/data/<plugin-id>/ and delete anything you did not deliberately edit.

To start from the bundled version of a file, use the customize-file.sh helper, which copies it into place and prints the destination. ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PLUGIN_DATA} only expand inside plugin-loaded skill files, so spell both paths out when running this yourself:

# paths for a marketplace install; adjust if you installed the plugin some other way,
# and confirm the data dir against `ls ~/.claude/plugins/data/`
PLUGIN_ROOT=~/.claude/plugins/marketplaces/umputun-cc-thingz/plugins/planning
PLUGIN_DATA=~/.claude/plugins/data/planning-umputun-cc-thingz

# project level, writes .claude/exec-plan/prompts/review.md
bash "$PLUGIN_ROOT/skills/exec/scripts/customize-file.sh" prompts/review.md

# user level, applies to all projects
bash "$PLUGIN_ROOT/skills/exec/scripts/customize-file.sh" prompts/review.md "$PLUGIN_DATA"

An override shadows the bundled default permanently and will not pick up changes from later plugin upgrades, so copy only the files you intend to edit. Delete the override to return to the bundled version.

Bundled prompts: task.md, fixer.md, review.md, codex-review.md, finalizer.md, stats.md, progress-file.md Bundled agents: quality.txt, implementation.txt, testing.txt, simplification.txt, documentation.txt, smells.txt

Customization patterns — two common shapes:

• Route the review fanout to named specialists. Override prompts/review.md to launch named Claude Code subagents (qa-expert, code-quality, go-test-expert, implementation-reviewer, documentation) instead of generic general-purpose. The override controls the subagent_type for each parallel specialist.
• Delegate to an existing skill. Override a prompt or agent file to instruct the spawned subagent to read another skill's SKILL.md and follow its workflow. Examples: override agents/smells.txt to delegate to a /smells skill; override prompts/finalizer.md to delegate to a /rebase-commits skill. Useful when an installed skill captures the workflow better than the bundled default.

Constraint — subagents in current Claude Code do not have the Agent tool, so they cannot spawn other subagents. prompts/review.md is therefore read by the main session orchestrator directly (used as a playbook), not given to a subagent — that is how the 5-specialist fanout actually runs in parallel. Single-agent leaf work (task.md, fixer.md, finalizer.md, codex-review.md, agents/smells.txt) runs as a spawned subagent because no further fan-out is needed. Any custom override that needs to fan out must follow the same playbook pattern.

Configuration via userConfig (prompted at plugin install):

External review contract — review phase 3 always runs through run-external-review.sh, which receives the external_review_cmd value and the resolved prompt. When the setting is empty it falls back to codex via run-codex.sh. A custom command must:

• be able to run shell commands and read files in the working tree — the prompt tells the reviewer to run a git diff, then read the plan file, the progress file, and source files for context. A plain text-in/text-out LLM CLI satisfies every other bullet here and reviews nothing
• accept the prompt as its final argument (the command string may carry flags, for example mytool review --strict; arguments containing spaces are not supported, so wrap those in a script)
• write findings to stdout, one per line, tagged CRITICAL, MAJOR, or MINOR, and print NO ISSUES FOUND when clean
• sandbox itself — the reviewer must not modify the working tree, since fixes are applied by a separate fixer agent
• exit 0 even when it reports findings
• read nothing from stdin — the script redirects it from /dev/null, so a tool that waits for input would hang the run rather than review it

The configured value is shell-parsed before the script sees it — Claude Code substitutes it into the command line that launches run-external-review.sh. It lands inside single quotes, so the shell passes it through as one argument and $, backtick, " and \ are inert, while spaces and ; are safe; the split into command and flags is done by the script's own read -ra. Only a literal ' cannot be expressed — wrap a command that needs one in a script and point the setting at that. Plugin config comes from user, flag, and policy settings only — never from project settings — so a checked-out repository cannot set this value.

Leaving the setting alone is supported and takes the codex fallback. Claude Code's skill-content substitution does not merge in the schema default the way the hook and MCP paths do: with no saved value it leaves the ${user_config.external_review_cmd} reference in the skill text verbatim. The script recognises that literal token as "not configured" and falls back to codex, printing a note on stderr — so a plugin that was never taken through /plugin configure still runs review phase 3.

The script exits 127 when the configured command (or codex) is not on PATH, which makes the run skip the phase instead of treating it as a review failure. Both such messages carry a run-external-review: marker on stderr, and the run requires that marker before it treats a 127 as a skip — so a 127 raised by the reviewer itself (a wrapper script whose own inner tool is missing) is reported as a reviewer failure rather than silently skipping the review.

The prompt reaches the tool as a single argv element read from a file, not pasted into the command line, since it contains backticks that a shell would otherwise run as command substitutions.

Environment variables read by run-codex.sh:

release-tools

Release workflow tools for creating versioned releases with auto-generated notes.

release — full release workflow: asks release type (hotfix/minor/major), auto-detects platform (GitHub/GitLab/Gitea), calculates semantic version, generates release notes grouped by type (features/improvements/f