| name | refactor |
| description | Multi-mode code and skill review for controlling drift as capability surface grows. Quick scan all plugins, commit-based tidying, contract-driven codebase quick scan, deep-review a single skill, holistic cross-plugin analysis, or docs consistency check. Triggers: "cwf:refactor", "/refactor", "tidy", "review skill", "cleanup code", "check docs consistency" |
Refactor (cwf:refactor)
Control drift across code, skills, and docs as teams install and author more capabilities.
Quick Reference
cwf:refactor Quick scan all marketplace skills
cwf:refactor --include-local-skills Quick scan marketplace + local skills
cwf:refactor --tidy [branch] Commit-based tidying (parallel sub-agents)
cwf:refactor --codebase Contract-driven whole-codebase quick scan
cwf:refactor --codebase --deep Codebase deep review with 4 expert sub-agents
cwf:refactor --skill <name> Deep review of a single skill (parallel sub-agents)
cwf:refactor --skill --holistic Cross-plugin analysis (parallel sub-agents)
cwf:refactor --docs Documentation consistency review
Philosophy:
cwf:refactor (no args) is a maintenance heartbeat for ecosystem-level drift detection.cwf:refactor --skill <name> is for focused diagnosis when one authored/installed skill needs targeted correction without paying the cost of full holistic analysis.- Portability is a default review axis across deep, holistic, and docs modes (no extra flag).
Mode Routing
Parse the user's input:
| Input | Mode |
|---|
| No args | Quick Scan |
--tidy or --tidy <branch> | Code Tidying |
--codebase | Codebase Quick Scan |
--codebase --deep | Codebase Deep Review |
--include-local-skills (no other mode flags) | Quick Scan + local skills |
--skill <name> | Deep Review |
--skill --holistic or --holistic | Holistic Analysis |
--docs | Docs Review |
Provenance Sidecars (Required)
Before using any criteria document, verify its provenance sidecar against the current live repository state (current skill/hook counts).
Verification command:
bash {CWF_PLUGIN_DIR}/scripts/provenance-check.sh --level inform --json
Provenance verification rules:
- Confirm the mode-relevant sidecar entry exists in the checker output.
- Compare sidecar
skill_count/hook_count with checker current.skills/current.hooks.
- If the sidecar is missing or stale, continue review but prepend a Provenance Warning and include the delta in the report.
Quick Scan Mode (no args)
Resolve session directory (for deterministic artifact persistence) using references/session-bootstrap.md with bootstrap key refactor-quick-scan.
Run the structural scan script and persist raw output:
bash {SKILL_DIR}/scripts/quick-scan.sh {REPO_ROOT} > {session_dir}/refactor-quick-scan.json
{REPO_ROOT} is the git repository root (5 levels up from SKILL.md in marketplace path, or use git rev-parse --show-toplevel).
Optional local-skill scope (portability hardening):
bash {SKILL_DIR}/scripts/quick-scan.sh \
{REPO_ROOT} \
--include-local-skills \
--local-skill-glob ".claude/skills/*/SKILL.md" > {session_dir}/refactor-quick-scan.json
Parse the JSON output and present a summary table. Also persist a concise summary to {session_dir}/refactor-summary.md:
| Plugin | Skill | Words | Lines | Flags |
|---|
- For each flagged skill (flag_count > 0), list the specific flags.
- Suggest: "Run
cwf:refactor --skill <name> for a deep review."
- Include
Mode: cwf:refactor (Quick Scan) and the scan command in the summary file.
After writing summary artifacts, run deterministic gate:
bash {CWF_PLUGIN_DIR}/scripts/check-run-gate-artifacts.sh \
--session-dir "{session_dir}" \
--stage refactor \
--strict \
--record-lessons
Code Tidying Mode (--tidy [branch])
Analyze recent commits for safe tidying opportunities — guard clauses, dead code removal, explaining variables. Based on Kent Beck's "Tidy First?" philosophy.
1. Get Target Commits
Run the script to get recent non-tidying commits:
bash {SKILL_DIR}/scripts/tidy-target-commits.sh 5 [branch]
- If branch argument provided (e.g.,
cwf:refactor --tidy develop), pass it to the script.
- If no branch specified, defaults to HEAD.
2. Parallel Analysis with Sub-agents
Resolve session directory using references/session-bootstrap.md with bootstrap key refactor-tidy.
Apply the context recovery protocol — for each commit N (1-indexed), check {session_dir}/refactor-tidy-commit-{N}.md.
For each commit hash that needs analysis, launch a parallel sub-agent using Task tool:
Task tool:
subagent_type: general-purpose
max_turns: 12
Each sub-agent prompt:
- Read
{SKILL_DIR}/references/tidying-guide.md for techniques, constraints, and output format
- Analyze commit diff:
git show {commit_hash}
- Check if changes still exist:
git diff {commit_hash}..HEAD -- {file} (skip modified regions)
- Return suggestions or "No tidying opportunities"
- Output Persistence: Write your complete analysis to:
{session_dir}/refactor-tidy-commit-{N}.md. At the very end of the file, append this sentinel marker on its own line: <!-- AGENT_COMPLETE -->
3. Aggregate Results
Read all result files from the session directory ({session_dir}/refactor-tidy-commit-{N}.md for each commit) and present:
# Tidying Analysis Results
## Commit: {hash} - {message}
- suggestion 1
- suggestion 2
## Commit: {hash} - {message}
- No tidying opportunities
Codebase Quick Scan Mode (--codebase)
Run a contract-driven quick scan across the repository codebase.
0. Resolve or Bootstrap Codebase Contract
Before scanning, resolve the repository-local codebase contract:
bash {SKILL_DIR}/scripts/bootstrap-codebase-contract.sh --json
Behavior:
- Default location:
{artifact_root}/codebase-contract.yaml
- If contract is missing: create a draft contract
- If contract exists: do not overwrite unless explicit force is used
- If bootstrap fails (
status=fallback with non-zero exit): stop this mode and fix bootstrap/path issues before scanning
Capture metadata for final summary:
CONTRACT_STATUS: created, existing, updated, or fallback (fallback is fail-safe and must halt the stage)CONTRACT_PATHCONTRACT_WARNING (optional)
Contract spec: references/codebase-contract.md
For shell strict-mode exceptions, use contract + file pragma dual control:
- contract allowlist:
checks.shell_strict_mode.file_overrides
- file pragma:
# cwf: shell-strict-mode relax reason="..." ticket="..." expires="YYYY-MM-DD"
For implementation/regression checks of codebase-contract behavior, run:
bash {SKILL_DIR}/scripts/check-codebase-contract-runtime.sh
1. Resolve Session Directory
Use references/session-bootstrap.md with bootstrap key refactor-codebase.
2. Run Contract-Driven Scan and Persist Raw Output
bash {SKILL_DIR}/scripts/codebase-quick-scan.sh \
{REPO_ROOT} \
--contract "{CONTRACT_PATH}" > {session_dir}/refactor-codebase-scan.json
{REPO_ROOT} is the git repository root (git rev-parse --show-toplevel).
scripts/codebase-quick-scan.sh delegates contract evaluation and findings aggregation to scripts/codebase-quick-scan.py as the backend implementation.
3. Summarize Findings
Read {session_dir}/refactor-codebase-scan.json and write {session_dir}/refactor-summary.md with:
Mode: cwf:refactor --codebase- Contract metadata (
CONTRACT_STATUS, CONTRACT_PATH, optional CONTRACT_WARNING)
- Scope summary (candidate/scanned/excluded files)
- Top findings table: severity, check, file, detail
- If no findings: explicit "No significant codebase tidy risks detected"
After writing summary artifacts, run deterministic gate:
bash {CWF_PLUGIN_DIR}/scripts/check-run-gate-artifacts.sh \
--session-dir "{session_dir}" \
--stage refactor \
--strict \
--record-lessons
Codebase Deep Review Mode (--codebase --deep)
Run codebase quick scan first, then add expert-lens deep review using 4 parallel expert sub-agents.
Full procedure: references/codebase-deep-review-flow.md
Execution contract:
- Resolve/bootstrap codebase contract (
bootstrap-codebase-contract.sh --json)
- Resolve session directory with references/session-bootstrap.md (
refactor-codebase-deep)
- Run codebase scan to
{session_dir}/refactor-codebase-scan.json
- Select experts to
{session_dir}/refactor-codebase-experts.json
- Launch 4 parallel experts (Fowler, Beck, Context 1, Context 2) and persist outputs with
<!-- AGENT_COMPLETE -->
- Merge scan + expert outputs into
{session_dir}/refactor-summary.md, then run gate
Deep Review Mode (--skill <name>)
Full procedure: references/deep-review-flow.md
Execution contract:
- Locate the target skill, read
SKILL.md + references/ + scripts/ + assets/
- Verify deep-review provenance (
review-criteria.provenance.yaml)
- Resolve session directory with references/session-bootstrap.md (
refactor-skill)
- Launch 2 parallel sub-agents (Structural 1-4, Quality+Concept 5-9) with output persistence sentinel
- Merge outputs into unified deep report and offer to apply changes
Holistic Mode (--skill --holistic or --holistic)
Cross-plugin analysis for global optimization. Read ALL skills and hooks, then analyze inter-plugin relationships.
Full procedure: references/holistic-review-flow.md
Execution contract:
- Build inventory from marketplace skills, hooks, and local skills
- Verify holistic criteria provenance (
holistic-criteria.provenance.yaml)
- Resolve session directory with references/session-bootstrap.md (
refactor-holistic)
- Launch 3 parallel sub-agents (Convention, Concept, Workflow) with output persistence sentinel
- Merge to holistic report and discuss prioritization with the user
Docs Review Mode (--docs)
Review documentation consistency with this fixed flow:
- Resolve/bootstrap docs contract (
bootstrap-docs-contract.sh)
- Deterministic tool pass (
markdownlint, local link check, doc-graph)
- Docs criteria provenance verification
- Contract-aware entry docs, project context, README, and cross-document consistency review
- Semantic quality and structural optimization synthesis (portability baseline always on)
Deterministic tool pass uses scripts/check-links.sh and scripts/doc-graph.mjs with markdownlint; for docs-contract runtime regression checks, run scripts/check-docs-contract-runtime.sh.
Use {SKILL_DIR}/references/docs-criteria.md for evaluation criteria, references/docs-contract.md for contract schema, and references/docs-review-flow.md for full --docs procedure (commands, sequence, and reporting scope).
Rules
- Deep Review and Holistic use perspective-based parallel sub-agents (not module-based)
- Deep Review: 2 agents (structural 1-4 + quality/concept/portability 5-9), single batch
- Holistic: 3 agents (Convention Compliance, Concept Integrity, Workflow Coherence), single batch after inline inventory
- Code Tidying: 1 agent per commit, all in one message
- Codebase Quick Scan: contract-driven deterministic scan, no sub-agents
- Codebase Deep Review: 4 expert sub-agents (fixed 2 + context 2) after codebase scan
- Docs Review: inline, no sub-agents (single-context synthesis over whole-repo graph and deterministic outputs)
- Docs Review must run the deterministic tool pass before semantic analysis
- In Docs Review, do not report lint/hook-detectable issues as standalone manual findings when tool output already covers them
- Sub-agents analyze and report; orchestrator merges. Sub-agents do not modify files
- All code fences must have a language specifier
References
