agentleFS
Sign inStart free
darkroomengineeringdarkroomengineering/cc-settings/skills/refactor/SKILL.md

refactor

Skill52 starsChanged 49 days agoMITView on GitHub

Behavior-preserving restructuring of code outside the current diff, such as extracting modules, renaming across files, or paying down debt. Triggers "refactor X", "restructure", "extract Y from Z". Just-changed code goes to /zero-tech-debt.

196 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ascii-diagram, debug-fix and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • SethGammonSkill

    ascii-diagram

    Generate perfectly aligned ASCII diagrams — architecture, flow, sequence, box-and-arrow. Uses a programmatic character-grid approach so alignment is guaranteed by math, not token prediction. Includes post-render verification.

    Also in 4 projects that use this

  • zebbernSkill

    debug-fix

    Find and fix a bug or issue — from any source (GitHub issue, error message, user report, or observed behavior)

    Also in 4 projects that use this

  • parcadeiSkill

    agent-context-isolation

    Agent Context Isolation

    Also in 3 projects that use this

  • parcadeiSkill

    agentica-infrastructure

    Reference guide for Agentica multi-agent infrastructure APIs

    Also in 3 projects that use this

  • +8 more from parcadei

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 169 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create each new agent with spawn_agent, deliver context to a running agent with send_message, trigger another turn for an idle existing …

    line 11
  2. Very specific:

    Standalone Codex branch: follow the lifecycle and serialization rules at the top.

    line 62

“Common” is measured: kept by at least 6 in 10 of the 169 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Refactoring Workflow

Standalone Codex

Create each new agent with spawn_agent, deliver context to a running agent with send_message, trigger another turn for an idle existing agent with followup_task, wait with wait_agent, and stop a current turn with interrupt_agent only when necessary. Never spawn codex-verifier and never run codex-run.ts from inside Codex.

Writers share the working tree unless the live host explicitly offers isolation. Assign non-overlapping ownership and serialize planner handoff, implementer, and test-writer phases; only read-only reviewers may overlap. Codex implementers are not promised Claude worktree isolation.

You are in Maestro orchestration mode. Delegate immediately.

Workflow

  1. Clarify - A refactor's target shape is rarely fixed by the request. Before exploring, run clarifying rounds through the host's question tool until no fork is left: target shape, what must not change, and what "done" looks like; recommendation first on each
  2. Explore - Spawn explore agent to analyze current code
  3. Plan - Spawn planner agent to design refactoring approach
  4. Implement - Spawn implementer agent to refactor
  5. Test - Spawn tester agent to verify behavior unchanged
  6. Review - Spawn reviewer agent to check quality
  7. Learn - Store patterns discovered during refactoring

Agent Delegation

Spawn explore and planner first — they accept thin prompts because they discover what they need from the codebase:

Agent(explore, "Analyze the code to refactor: $ARGUMENTS. Identify patterns, issues, dependencies.")
Agent(planner, "Design refactoring approach based on analysis. Keep behavior unchanged.")

Claude: then assemble the implementer prompt from the actual planner output. The Claude implementer runs in an isolated worktree with no access to prior agent results, so paste the real plan — not "according to plan":

  • The user's refactor target ($ARGUMENTS) verbatim
  • The planner's step-by-step plan, including file paths and each move/rename/extract operation
  • Any "preserve behavior" invariants the planner called out
  • The test command that must remain green
  • Scope: "only the files in the plan; do not touch anything else"

Now spawn:

Agent(implementer, "<the assembled briefing above — all five items inline>")
Agent(tester, "Verify refactored code behaves identically to original.")
Agent(reviewer, "Review refactoring for quality and completeness.")

Standalone Codex branch: follow the lifecycle and serialization rules at the top. Use a fresh read-only reviewer for the independent pass after the writer and tester finish.

Refactors are a top source of subtle regressions. The one cross-model Codex review per PR (run by /ship, or on request) covers the refactor diff; do not run a separate Codex pass here. The reviewer agent above is the in-workflow review.

Output

Return a summary:

  • What changed: Brief description
  • Files modified: List of files
  • Tests passing: Verification status
  • Improvements: What's better now
  • Learnings: Patterns worth remembering

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free