[AUTO-GUARD-1] Technical Debt: cli/commands/plan.py is a 4567-line monolith with 50+ functions #9950

Open
opened 2026-04-16 06:54:38 +00:00 by HAL9000 · 0 comments
Owner

Metadata

  • Commit Message: refactor(cli): split plan.py monolith into focused submodules
  • Branch: refactor/auto-guard-1-plan-py-split

Background and Context

src/cleveragents/cli/commands/plan.py is a 4567-line file containing 50+ functions. This is the largest file in the codebase and represents a significant maintenance burden. Several individual functions exceed 50 lines.

File: src/cleveragents/cli/commands/plan.py
Lines: 4567
Function count: 50+ functions

Large functions identified:

  • tell (line 846) — streaming tell command (~116 lines)
  • build (line 962) — build command (~98 lines)
  • execute_plan (line 2289) — execute plan command (~238 lines)
  • lifecycle_apply_plan (line 2527) — apply plan command (~152 lines)
  • plan_status (line 2679) — plan status display (~89 lines)
  • plan_errors (line 2768) — plan errors display (~126 lines)
  • lifecycle_list_plans (line 2894) — list plans (~252 lines)
  • correct_decision (line 3486) — correction command (~240 lines)
  • rollback_plan (line 3904) — rollback command (~270 lines)
  • _create_sandbox_for_plan (line 1348) — sandbox creation (~55 lines)
  • _apply_sandbox_changes (line 1403) — sandbox changes (~231 lines)

Additional concern: Repeated inline imports

The file contains 94 from cleveragents import statements, many of which are repeated inside function bodies (e.g., PlanService and ProjectService are imported inside 10+ different functions instead of at module level).

Expected Behavior

plan.py is split into focused, single-responsibility modules, each under ~300 lines. All existing CLI commands continue to work identically. Imports are consolidated at module level. The codebase is easier to navigate, test, and maintain.

Acceptance Criteria

  • plan.py is split into at least 4 focused submodules (e.g., plan_tell.py, plan_lifecycle.py, plan_status.py, plan_correction.py, plan_sandbox.py)
  • No individual resulting file exceeds 500 lines
  • All inline from cleveragents imports are moved to module-level imports
  • All existing CLI commands (tell, build, execute, apply, status, errors, list, correct, rollback, etc.) continue to function identically
  • Test coverage remains ≥ 97% after the split
  • nox passes with no regressions

Subtasks

  • Audit plan.py and group functions by responsibility domain
  • Create plan_tell.py — tell/build/streaming commands
  • Create plan_lifecycle.py — execute/apply/cancel/revert commands
  • Create plan_status.py — status/list/errors display commands
  • Create plan_correction.py — correct/rollback/explain commands
  • Create plan_sandbox.py — sandbox helper functions
  • Move all inline imports to module-level in each new file
  • Update plan.py (or a new __init__.py) to re-export all public symbols for backward compatibility
  • Run nox -s coverage_report and verify coverage ≥ 97%
  • Run nox (all default sessions) and fix any errors

Definition of Done

This issue is closed when:

  • All subtasks above are checked off
  • plan.py no longer exists as a monolith (or is reduced to a thin router/re-export shim)
  • All CLI commands pass integration tests
  • nox passes with coverage ≥ 97%
  • A pull request is merged to master on the branch refactor/auto-guard-1-plan-py-split

Summary

src/cleveragents/cli/commands/plan.py is a 4567-line file containing 50+ functions. This is the largest file in the codebase and represents a significant maintenance burden. Several individual functions exceed 50 lines.

Details

Large functions identified:

  • tell (line 846) — streaming tell command (~116 lines)
  • build (line 962) — build command (~98 lines)
  • execute_plan (line 2289) — execute plan command (~238 lines)
  • lifecycle_apply_plan (line 2527) — apply plan command (~152 lines)
  • plan_status (line 2679) — plan status display (~89 lines)
  • plan_errors (line 2768) — plan errors display (~126 lines)
  • lifecycle_list_plans (line 2894) — list plans (~252 lines)
  • correct_decision (line 3486) — correction command (~240 lines)
  • rollback_plan (line 3904) — rollback command (~270 lines)
  • _create_sandbox_for_plan (line 1348) — sandbox creation (~55 lines)
  • _apply_sandbox_changes (line 1403) — sandbox changes (~231 lines)

Additional concern: Repeated inline imports

The file contains 94 from cleveragents import statements, many of which are repeated inside function bodies (e.g., PlanService and ProjectService are imported inside 10+ different functions instead of at module level).

Recommendation

Split plan.py into focused modules:

  1. plan_tell.py — tell/build/streaming commands
  2. plan_lifecycle.py — execute/apply/cancel/revert commands
  3. plan_status.py — status/list/errors display commands
  4. plan_correction.py — correct/rollback/explain commands
  5. plan_sandbox.py — sandbox helper functions

References

  • src/cleveragents/cli/commands/plan.py
  • ADR-021: CLI and Output Rendering

Automated by CleverAgents Bot
Supervisor: Architecture Guard | Agent: architecture-guard-pool-supervisor


Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(cli): split plan.py monolith into focused submodules` - **Branch**: `refactor/auto-guard-1-plan-py-split` ## Background and Context `src/cleveragents/cli/commands/plan.py` is a 4567-line file containing 50+ functions. This is the largest file in the codebase and represents a significant maintenance burden. Several individual functions exceed 50 lines. **File:** `src/cleveragents/cli/commands/plan.py` **Lines:** 4567 **Function count:** 50+ functions ### Large functions identified: - `tell` (line 846) — streaming tell command (~116 lines) - `build` (line 962) — build command (~98 lines) - `execute_plan` (line 2289) — execute plan command (~238 lines) - `lifecycle_apply_plan` (line 2527) — apply plan command (~152 lines) - `plan_status` (line 2679) — plan status display (~89 lines) - `plan_errors` (line 2768) — plan errors display (~126 lines) - `lifecycle_list_plans` (line 2894) — list plans (~252 lines) - `correct_decision` (line 3486) — correction command (~240 lines) - `rollback_plan` (line 3904) — rollback command (~270 lines) - `_create_sandbox_for_plan` (line 1348) — sandbox creation (~55 lines) - `_apply_sandbox_changes` (line 1403) — sandbox changes (~231 lines) ### Additional concern: Repeated inline imports The file contains 94 `from cleveragents` import statements, many of which are repeated inside function bodies (e.g., `PlanService` and `ProjectService` are imported inside 10+ different functions instead of at module level). ## Expected Behavior `plan.py` is split into focused, single-responsibility modules, each under ~300 lines. All existing CLI commands continue to work identically. Imports are consolidated at module level. The codebase is easier to navigate, test, and maintain. ## Acceptance Criteria - [ ] `plan.py` is split into at least 4 focused submodules (e.g., `plan_tell.py`, `plan_lifecycle.py`, `plan_status.py`, `plan_correction.py`, `plan_sandbox.py`) - [ ] No individual resulting file exceeds 500 lines - [ ] All inline `from cleveragents` imports are moved to module-level imports - [ ] All existing CLI commands (`tell`, `build`, `execute`, `apply`, `status`, `errors`, `list`, `correct`, `rollback`, etc.) continue to function identically - [ ] Test coverage remains ≥ 97% after the split - [ ] `nox` passes with no regressions ## Subtasks - [ ] Audit `plan.py` and group functions by responsibility domain - [ ] Create `plan_tell.py` — tell/build/streaming commands - [ ] Create `plan_lifecycle.py` — execute/apply/cancel/revert commands - [ ] Create `plan_status.py` — status/list/errors display commands - [ ] Create `plan_correction.py` — correct/rollback/explain commands - [ ] Create `plan_sandbox.py` — sandbox helper functions - [ ] Move all inline imports to module-level in each new file - [ ] Update `plan.py` (or a new `__init__.py`) to re-export all public symbols for backward compatibility - [ ] Run `nox -s coverage_report` and verify coverage ≥ 97% - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done This issue is closed when: - All subtasks above are checked off - `plan.py` no longer exists as a monolith (or is reduced to a thin router/re-export shim) - All CLI commands pass integration tests - `nox` passes with coverage ≥ 97% - A pull request is merged to `master` on the branch `refactor/auto-guard-1-plan-py-split` ## Summary `src/cleveragents/cli/commands/plan.py` is a 4567-line file containing 50+ functions. This is the largest file in the codebase and represents a significant maintenance burden. Several individual functions exceed 50 lines. ## Details ### Large functions identified: - `tell` (line 846) — streaming tell command (~116 lines) - `build` (line 962) — build command (~98 lines) - `execute_plan` (line 2289) — execute plan command (~238 lines) - `lifecycle_apply_plan` (line 2527) — apply plan command (~152 lines) - `plan_status` (line 2679) — plan status display (~89 lines) - `plan_errors` (line 2768) — plan errors display (~126 lines) - `lifecycle_list_plans` (line 2894) — list plans (~252 lines) - `correct_decision` (line 3486) — correction command (~240 lines) - `rollback_plan` (line 3904) — rollback command (~270 lines) - `_create_sandbox_for_plan` (line 1348) — sandbox creation (~55 lines) - `_apply_sandbox_changes` (line 1403) — sandbox changes (~231 lines) ### Additional concern: Repeated inline imports The file contains 94 `from cleveragents` import statements, many of which are repeated inside function bodies (e.g., `PlanService` and `ProjectService` are imported inside 10+ different functions instead of at module level). ## Recommendation Split `plan.py` into focused modules: 1. `plan_tell.py` — tell/build/streaming commands 2. `plan_lifecycle.py` — execute/apply/cancel/revert commands 3. `plan_status.py` — status/list/errors display commands 4. `plan_correction.py` — correct/rollback/explain commands 5. `plan_sandbox.py` — sandbox helper functions ## References - `src/cleveragents/cli/commands/plan.py` - ADR-021: CLI and Output Rendering --- **Automated by CleverAgents Bot** Supervisor: Architecture Guard | Agent: architecture-guard-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9950
No description provided.