From nexus
Analyze code and suggest refactoring improvements with agent-driven analysis. Runs in the current working tree by default — set `worktree.enabled: true` in `.claude/configuration.yml` to isolate work in a git worktree.
npx claudepluginhub nexus-a1/claude-skills --plugin nexusThis skill is limited to using the following tools:
Git status: !`git status --short 2>/dev/null || echo "Not a git repository"`
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Git status: !git status --short 2>/dev/null || echo "Not a git repository"
Recently modified files: !git diff --name-only HEAD 2>/dev/null || echo "No recent changes"
Current directory: !pwd
Arguments: $ARGUMENTS
# Source resolve-config: marketplace installs get ${CLAUDE_PLUGIN_ROOT} substituted
# inline before bash runs; ./install.sh users fall back to ~/.claude. If neither
# path resolves, fail loudly rather than letting resolve_artifact be undefined.
if [ -f "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh" ]; then
source "${CLAUDE_PLUGIN_ROOT}/shared/resolve-config.sh"
elif [ -f "$HOME/.claude/shared/resolve-config.sh" ]; then
source "$HOME/.claude/shared/resolve-config.sh"
else
echo "ERROR: resolve-config.sh not found. Install via marketplace or run ./install.sh" >&2
exit 1
fi
REFACTOR_EXEC_MODE=$(resolve_exec_mode refactor team)
Use $REFACTOR_EXEC_MODE to determine team vs sub-agent behavior in Steps 3 and 5.1.
When running QA agents in parallel (Step 5.1 quality gate loop), agents MUST NOT write to the same file:
See ~/.claude/shared/write-safety.md for the full conventions.
If resolve_worktree_enabled returns "true", enter a worktree before making changes:
Single mode (WORKSPACE_MODE == "single"):
EnterWorktree(name: "refactor-{short_slug}") before Step 5 (Apply Fixes)ExitWorktree(action: "keep")Multi mode (WORKSPACE_MODE == "multi"):
WT_ROOT=$(resolve_worktree_root)
REFACTOR_WORKSPACE="${WT_ROOT}/refactor-{short_slug}"
mkdir -p "$REFACTOR_WORKSPACE"
# Create worktree only for services that need changes
for svc in {affected_services}; do
svc_path=$(resolve_service_path "$svc")
wt_path="${REFACTOR_WORKSPACE}/${svc}"
[[ -d "$wt_path" ]] && continue
git -C "$svc_path" worktree add "$wt_path" HEAD
done
Analyze code for refactoring opportunities and optionally apply fixes using the refactorer agent. Analysis is delegated to specialized agents for higher-quality findings.
From $ARGUMENTS:
src/Controller/UserController.php → Specific filesrc/Service → Directory (all source files)src/**/*.ts → Pattern matchLanguage Detection:
Detect the primary language from file extensions:
| Extension | Language | Framework Detection |
|---|---|---|
.php | PHP | Symfony (if composer.json has symfony/*) |
.ts, .tsx | TypeScript | React (if .tsx or react in package.json) |
.js, .jsx | JavaScript | React, Node.js, Express |
.py | Python | Django, Flask, FastAPI |
.go | Go | Standard library patterns |
.rs | Rust | Cargo project structure |
| Other | Generic | Universal analysis only |
Filtering:
vendor/, node_modules/, var/cache/, dist/, build/, .next/, __pycache__/, target/No files found:
No source files found to analyze
Suggestions:
- Provide a specific file: /refactor src/Controller/UserController.php
- Provide a directory: /refactor src/Service
Use Task tool with subagent_type: "Explore":
Prompt: Analyze the codebase context for refactoring the following files.
Target files:
{file_list}
Language: {detected_language}
Framework: {detected_framework or "none"}
Research and document:
1. Architecture patterns used (layered, hexagonal, MVC, etc.)
2. Coding conventions and style
3. Dependency injection / dependency management patterns
4. Test patterns and approximate coverage
5. Related files that may be affected by changes to the target files
6. Framework-specific conventions (if any)
Return a structured context report.
Use Task tool with subagent_type: "code-reviewer":
Prompt: Analyze the following files for refactoring opportunities. This is a REFACTORING analysis, NOT a PR review — focus on structural improvements, not bugs.
Target files:
{file_list}
Codebase context:
{exploration_results}
Language: {detected_language}
Framework: {detected_framework}
Analyze for:
A. SOLID Principles
- Single Responsibility: classes/methods doing too much
- Open/Closed: hard-coded values, excessive conditionals
- Liskov Substitution: concrete types instead of interfaces
- Interface Segregation: large interfaces
- Dependency Inversion: direct instantiation, concrete dependencies
B. Code Smells
- Long methods (>30 lines)
- Large classes (>300 lines, >10 methods)
- Deep nesting (>3 levels)
- Duplicate code
- Dead code (unused methods/properties/functions)
- Magic numbers/strings
- Data clumps (repeated parameter groups)
C. Language-Specific Improvements
- Missing type annotations / type hints
- Outdated syntax patterns that have modern equivalents
- Framework best practice violations
- Idiomatic improvements for {detected_language}
Categorize each finding as:
- CRITICAL: significant design issues, high-impact improvements
- IMPORTANT: meaningful improvements, moderate impact
- SUGGESTION: nice-to-haves, low impact
For each finding, provide:
- File path and line number
- Problem description
- Specific refactoring recommendation
- Estimated impact (high/medium/low)
Present findings from the code-reviewer analysis.
For each file:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{file_path}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Overview:
Language: {language}
Lines: {count}
Methods/Functions: {count}
CRITICAL:
Line {N}: {description}
Problem: {problem}
Suggestion: {how to fix}
IMPORTANT:
Line {N}: {description}
Problem: {problem}
Fix: {specific change}
SUGGESTIONS:
Line {N}: {description}
Improvement: {improvement}
Priority Actions:
1. {most important}
2. {next}
3. {etc}
Summary across all files:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Refactoring Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files Analyzed: {count}
Language: {detected_language}
Total Issues: {count}
CRITICAL: {count}
IMPORTANT: {count}
SUGGESTIONS: {count}
Top Priorities:
1. {highest impact issue}
2. {next}
3. {etc}
After presenting the report:
Use AskUserQuestion:
For each selected fix, use Task tool with subagent_type: "refactorer":
Prompt: Apply the following refactoring to {file_path}:
Issue: {description}
Location: Line {N}
Refactoring: {specific change to make}
Requirements:
- Preserve exact behavior
- Follow existing code style
- Run tests after changes
Report results:
Applied: {description}
File: {file_path}
Lines changed: {N}
Tests: {passed|failed}
Only run if fixes were applied in Step 5.
After fixes are applied, enter a review→fix loop (max 3 iterations) to ensure quality.
Execution mode: Determined by $REFACTOR_EXEC_MODE.
┌──────────────────────────────────────────────────┐
│ QUALITY GATE LOOP (max 3 iterations) │
│ │
│ ┌─► code-reviewer validates changes │
│ │ test-writer checks coverage │
│ │ quality-guard challenges both │
│ │ │ │
│ │ All gates passed? │
│ │ YES → PASS → exit loop │
│ │ NO ↓ │
│ │ refactorer fixes issues (autonomous) │
│ └───────┘ │
│ │
│ Max iterations reached → report to user │
└──────────────────────────────────────────────────┘
If $REFACTOR_EXEC_MODE = "subagent":
Execute in a single message with multiple Task tool calls:
Task 1 — Use Task tool with subagent_type: "code-reviewer":
Prompt: Validate the refactoring changes just applied. This is a POST-REFACTORING validation — check that changes are structurally sound.
Diff of changes:
{git_diff_of_refactoring}
Original issues that were fixed:
{list_of_fixed_issues}
Check:
1. Were the original issues properly resolved?
2. Were any NEW structural issues introduced by the refactoring?
3. Is the code structurally better than before?
Return: Validation result with verdict:
- PASS: all issues resolved, no new issues
- FAIL: list each new issue with file, line, description, and fix suggestion
Task 2 — Use Task tool with subagent_type: "test-writer":
Prompt: Check test coverage for the refactored files and add tests if needed.
Refactored files:
{list_of_modified_files}
Changes made:
{summary_of_refactorings}
Requirements:
- Verify existing tests still cover the refactored code
- Add tests for any logic paths that lost coverage due to structural changes
- Follow existing test patterns in the codebase
- Do NOT add tests for trivial changes (type hints, syntax updates, renames)
- Only add tests where refactoring introduced new code paths (e.g., extracted classes/methods)
After both complete, run the skeptic:
Task 3 — Use Task tool with subagent_type: "quality-guard":
Prompt: Challenge the refactoring review findings (Level 2 — Implementation Validation).
Refactoring diff: {git_diff_of_refactoring}
Code-reviewer findings: {code_reviewer_output}
Test-writer findings: {test_writer_output}
Verify:
1. Did code-reviewer catch all structural regressions? Check the diff yourself.
2. Do the new tests actually cover the refactored paths, or are they trivial?
3. Are there behavioral changes disguised as "refactoring"?
Produce a Quality Review Gates report.
If $REFACTOR_EXEC_MODE = "team" (default):
Create a team for the quality gate review:
TeamCreate(team_name="refactor-qa")
TaskCreate: "Validate refactoring changes" (T1)
description: |
Diff: {git_diff_of_refactoring}. Original issues: {list_of_fixed_issues}.
Check structural soundness. Share findings with teammates.
TaskCreate: "Check test coverage" (T2)
description: |
Refactored files: {list_of_modified_files}. Changes: {summary_of_refactorings}.
Add tests for new code paths. Share coverage gaps with teammates.
TaskCreate: "Challenge review findings" (T3) — depends on T1, T2
description: |
Wait for code-reviewer and test-writer. Then verify their findings against actual code.
Use SendMessage to challenge specific agents with evidence.
[PARALLEL - Single message with multiple Task calls]
Task tool: name: "refactor-reviewer", subagent_type: "code-reviewer", team_name: "refactor-qa"
Task tool: name: "refactor-tester", subagent_type: "test-writer", team_name: "refactor-qa"
Task tool: name: "refactor-skeptic", subagent_type: "quality-guard", team_name: "refactor-qa"
Assign tasks. Monitor. Skeptic challenges via SendMessage. Agents resolve gates autonomously. Collect results and TeamDelete.
If code-reviewer returns FAIL or skeptic raises BLOCKING gates, dispatch the refactorer agent to fix them:
Use Task tool with subagent_type: "refactorer":
Prompt: Fix the following issues found during post-refactoring review:
{list_of_new_issues_from_reviewer_and_skeptic}
These issues were introduced during the previous refactoring pass. Fix them while preserving the improvements already made.
Requirements:
- Fix each listed issue
- Preserve exact behavior
- Follow existing code style
- Run tests after changes
Then return to Iteration Step A (review again).
On PASS: Present results and exit. In team mode, send shutdown_request to all teammates and TeamDelete.
On max iterations (3) reached: Present current state and remaining issues to the user. Do NOT continue looping. Clean up team if in team mode.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quality Gate Result
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Iterations: {count}/3
Verdict: {PASS | NEEDS_ATTENTION}
Code Review:
Original issues resolved: {count}/{total}
New issues introduced and fixed: {count}
Remaining issues: {count or "none"}
Skeptic Validation:
Verdict: {APPROVED | CONDITIONAL}
Gates: {resolved}/{raised}
Test Coverage:
Tests passing: {yes/no}
New tests added: {count}
Coverage gaps: {none | list}
If analysis finds no significant issues:
{file_path}
Code follows best practices:
- Clean separation of concerns
- Proper dependency management
- Strong typing
- Appropriate method length
No refactoring needed.
File too large (>1000 lines):
{file} is very large ({N} lines)
This itself is a code smell - consider splitting.
Analyzing anyway...
Too many files:
Found {N} source files in {path}
Analyzing the 20 most recently modified.
Run /refactor on specific directories for full coverage.