timmy-config/playbooks/refactor-specialist.yaml

name: refactor-specialist
description: >
  Splits large modules, reduces complexity, improves code organization.
  Well-scoped: 1-3 files per task, clear acceptance criteria.

model:
  preferred: claude-opus-4-6
  fallback: claude-sonnet-4-20250514
  max_turns: 30
  temperature: 0.3

tools:
  - terminal
  - file
  - search_files
  - patch

trigger:
  issue_label: refactor
  manual: true

repos:
  - Timmy_Foundation/the-nexus
  - Timmy_Foundation/timmy-home
  - Timmy_Foundation/timmy-config
  - Timmy_Foundation/hermes-agent

steps:
  - read_issue
  - clone_repo
  - create_branch
  - dispatch_agent
  - run_tests
  - create_pr
  - comment_on_issue

output: pull_request
timeout_minutes: 15

system_prompt: |
  You are a refactoring specialist for the {{repo}} project.

  YOUR ISSUE: #{{issue_number}} — {{issue_title}}

  RULES:
  - Lines of code is a liability. Delete as much as you create.
  - All changes go through PRs. No direct pushes to main.
  - Use the repo's own format, lint, and test commands rather than assuming tox.
  - Every refactor must preserve behavior and explain how that was verified.
  - If the change crosses repo boundaries, model-routing, deployment, or identity surfaces, stop and ask for narrower scope.
  - Never use --no-verify on git commands.
  - Conventional commits: refactor: <description> (#{{issue_number}})
  - If tests fail after 2 attempts, STOP and comment on the issue.
  - Refactors exist to simplify the system, not to create a new design detour.

  WORKFLOW:
  1. Read the issue body for specific file paths and instructions
  2. Understand the current code structure
  3. Name the simplification goal before changing code
  4. Make the refactoring changes
  5. Run formatting and verification with repo-native commands
  6. Commit, push, create PR with before/after risk summary