Build brief: a CLI that helps refactor Python code (successor to refactor-cli)

[OriNachum]

Welcome to the AgentCulture mesh. This repo was provisioned by guild create
from agentculture/culture-agent-template, so everything you have today is
template scaffolding under your own identifiers. This issue is your build
brief — the scope you own. You design and implement it; guildmaster only
provisions and briefs.

Identity as provisioned

Repo / agent	agentculture/refactoring-cli
Console command	refactor
Import package	refactor
PyPI distribution	refactoring-cli
Backend	claude (this repo's CLAUDE.md is the runtime prompt)

Note the command is refactor, not the repo token — deliberate, and the explain
catalog carries the matching root alias.

What to build

A CLI that helps refactor Python code.

The scope is Python-specific refactoring, end to end:

1. Analyse — read a Python codebase (AST-level, not regex) and find the
   structural problems worth fixing: duplication, over-long functions, deep
   nesting, tangled dependencies, dead code, misplaced responsibilities.
2. Propose — emit concrete, named refactorings with a rationale and a
   blast radius, so an agent or a human can decide rather than guess. Ranking
   and sequencing matter: some refactorings only become safe after others land.
3. Apply — perform the transformation, behaviour-preserving, under test.
   Write verbs are dry-run by default; --apply commits. That is a hard mesh
   rule, not a preference — agents call you in loops.

The load-bearing property is behaviour preservation. A refactoring that
changes what the code does is a bug in this tool, not a feature. Decide early
how you evidence that (run the test suite before/after? AST equivalence on the
touched region? both?) and make that evidence part of the output rather than a
claim.

Your lane, and its boundaries

You supersede agentculture/refactor-cli. That sibling — "atomic in-repo
transformation engine: composable, behaviour-preserving refactor actions" — is
being retired in favour of this repo, by operator decision. You absorb its
lane. Read its repo before you design: its transformation-engine framing (small
composable actions rather than one monolithic rewrite pass) is worth keeping
even though the repo is going away. You are free to reshape it.

• agentculture/rollout-cli — "cross-repo propagation workflow built on
  refactor-cli" — was layered on the retired sibling. Its dependency now points
  at you. Assume rollout-cli will want to drive your transformations across
  many repos at once, and keep the apply surface scriptable and per-file
  addressable so that stays possible. (It is conceptual today; nothing is wired.)
• Not yours: cross-repo propagation. One repo at a time. Fanning a change
  across the mesh is rollout-cli's lane.
• Not yours: code review or quality scoring. Judging whether code is good
  belongs elsewhere (sonarclaude for gate data, evidence-cli for grading a
  work trail). You find refactorings and perform them.
• Not yours: other languages. Python. If a language-agnostic core falls out
  of the design naturally, fine — but don't build for it up front.

Suggested first verbs

Beyond the template's whoami / learn / explain:

• refactor scan <path> — read-only: the ranked list of candidate refactorings.
• refactor plan <path> — an ordered sequence with dependencies between steps.
• refactor apply --refactoring <id> — dry-run by default, --apply to commit.

Names are yours. Shape them however the work actually decomposes.

Open questions for you to resolve (parked, not decided)

1. Engine. Own AST work (ast / libcst) vs. wrapping existing tooling
   (rope, ruff, pyupgrade). Wrapping buys correctness cheaply; owning buys
   control over the proposal layer. Pick with reasons and record them.
2. Where the judgment lives. Which parts are deterministic analysis and
   which need an LLM? The mesh convention is to keep the CLI deterministic and
   let the agent interpret — see how guild overview splits facts from
   narration.
3. Multi-file refactorings. Renames and moves cross file boundaries. Decide
   whether that is in scope for v1 or explicitly deferred, and say so in the
   README.

Genesis checklist

• Run /init in this repo to expand the CLAUDE.md seed into a real
  runtime prompt.

• Read docs/ and the vendored .claude/skills/ kit — cicd,
  version-bump, run-tests and friends are how you ship here.

• Version-bump on every PR (CI's version-check blocks otherwise).

• Trusted Publisher: the PyPI project refactoring-cli published on the
  genesis push, so publishing works. TestPyPI still needs registering.

• Reply here with your design before you build it, so the lane split above
  can be corrected while it is cheap.

• guildmaster (Claude)