claude-simplify-wrapper

Simplify Loop

Input: a git base SHA/ref to simplify against (for example: <sha> or HEAD~1).

Preconditions

• Confirm you are in the intended repo: git rev-parse --show-toplevel
• Ensure you have a base commit SHA (prefer the commit from before the change set).
• Start from a clean working tree (required):
  • git status --porcelain should be empty.
• Ensure git can create commits (stop if missing):
  • If commits fail due to missing identity, configure user.name and user.email.
• Only claude CLI is required (no codex dependency).

Scope / intent

• This is a simplification pass, not a general code review.
• Invokes Claude's built-in /simplify skill which runs three parallel agents internally:
  • Code reuse (find and eliminate duplication)
  • Code quality (simplify convoluted logic)
  • Code efficiency (remove unnecessary work)
• Changes are validated (build/lint/test) and committed automatically.

Architecture

Two-phase per iteration:

1. Simplify subprocess — Invokes claude with the /simplify prompt. The built-in skill handles its own three parallel agents and applies fixes directly to the working tree.
2. Validate+commit subprocess — A second claude subprocess that runs the repo's standard build/lint/test commands, fixes only breakages introduced by the simplify phase, stages and commits all changes, and emits LOOP_STATUS: {...} so the wrapper can decide whether to continue.

The loop stops when:

• The simplify phase produces no working-tree changes (nothing to simplify)
• The validate phase fails to make checks green
• Max iterations reached

Expected runtime

Typically runs 5–20 minutes per iteration. Allow at least 30 minutes for a single iteration.

Do not interrupt/restart the subagent if it looks stuck. The loop script owns stuck/timeout handling and will exit on its own when it completes or when --timeout is reached.

Run

resolve_skill_dir() {
  local name="$1"
  local repo_root=""
  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

  local candidates=(
    "$repo_root/.agents/skills/$name"
    "$repo_root/.claude/skills/$name"
    "$HOME/.agents/skills/$name"
    "$HOME/.codex/skills/$name"
    "$HOME/.claude/skills/$name"
  )

  for d in "${candidates[@]}"; do
    if [[ -d "$d" ]]; then
      echo "$d"
      return 0
    fi
  done

  echo "Error: skill '$name' not found in repo-scoped or user-scoped skill dirs." >&2
  return 1
}

SIMPLIFY_SKILL_DIR="$(resolve_skill_dir claude-simplify-wrapper)"
python3 "$SIMPLIFY_SKILL_DIR/scripts/run_simplify_loop.py" <base-sha>