Refactor: Unify API Naming Conventions and Method Signatures #8885

Open
opened 2026-04-14 03:23:19 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Commit Message: refactor(services): unify API naming conventions and method signatures across PlanService and ProjectService
  • Branch: refactor/unify-api-naming-conventions

Background and Context

There are inconsistencies in the naming conventions and method signatures of the public API, particularly between the PlanService and ProjectService classes. These inconsistencies make the API more difficult to learn and use, and can lead to errors.

Evidence:

  • Creation: PlanService.create_plan vs. ProjectService.initialize_project.
  • Listing: PlanService.list_plans vs. ProjectService.list_projects.
  • Getting by name: PlanService.switch_to_plan vs. ProjectService.get_project_by_name.
  • Current item: PlanService.get_current_plan vs. ProjectService.get_current_project.

Impacted Files:

  • src/cleveragents/application/services/plan_service.py
  • src/cleveragents/application/services/project_service.py
  • Other services in src/cleveragents/application/services/ may also be affected.

Relevant Specification Sections:

  • ADR-001-layered-architecture.md

Expected Behavior

All public API methods across service classes follow a consistent naming convention (e.g., create_*, get_*, list_*) and consistent method signatures for similar operations. The API is predictable and easy to learn.

Acceptance Criteria

  • A consistent naming convention is documented and agreed upon for all public service API methods
  • ProjectService.initialize_project is renamed to ProjectService.create_project (or equivalent agreed convention)
  • PlanService.switch_to_plan is renamed to PlanService.get_plan_by_name (or equivalent agreed convention)
  • All other services in src/cleveragents/application/services/ are audited and refactored to follow the new convention
  • Method signatures for similar operations (e.g., listing, filtering) are consistent across services
  • All callers of renamed methods are updated
  • All existing tests pass after the refactor
  • No public API regressions are introduced

Subtasks

  • Audit all service classes in src/cleveragents/application/services/ and document current naming inconsistencies
  • Propose and agree on a unified naming convention (e.g., create_*, get_*, list_*, delete_*)
  • Rename ProjectService.initialize_projectcreate_project (or agreed name)
  • Rename PlanService.switch_to_planget_plan_by_name (or agreed name)
  • Audit and align method signatures for listing/filtering operations across all services
  • Update all callers of renamed/refactored methods throughout the codebase
  • Run full test suite and fix any failures
  • Update any relevant documentation or docstrings

Definition of Done

This issue should be closed when:

  • All service classes in src/cleveragents/application/services/ follow a consistent, documented naming convention
  • All method signatures for similar operations are consistent
  • All callers are updated and the full test suite passes
  • No public API regressions exist

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


Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit Message**: `refactor(services): unify API naming conventions and method signatures across PlanService and ProjectService` - **Branch**: `refactor/unify-api-naming-conventions` ## Background and Context There are inconsistencies in the naming conventions and method signatures of the public API, particularly between the `PlanService` and `ProjectService` classes. These inconsistencies make the API more difficult to learn and use, and can lead to errors. **Evidence:** * **Creation:** `PlanService.create_plan` vs. `ProjectService.initialize_project`. * **Listing:** `PlanService.list_plans` vs. `ProjectService.list_projects`. * **Getting by name:** `PlanService.switch_to_plan` vs. `ProjectService.get_project_by_name`. * **Current item:** `PlanService.get_current_plan` vs. `ProjectService.get_current_project`. **Impacted Files:** * `src/cleveragents/application/services/plan_service.py` * `src/cleveragents/application/services/project_service.py` * Other services in `src/cleveragents/application/services/` may also be affected. **Relevant Specification Sections:** * ADR-001-layered-architecture.md ## Expected Behavior All public API methods across service classes follow a consistent naming convention (e.g., `create_*`, `get_*`, `list_*`) and consistent method signatures for similar operations. The API is predictable and easy to learn. ## Acceptance Criteria - [ ] A consistent naming convention is documented and agreed upon for all public service API methods - [ ] `ProjectService.initialize_project` is renamed to `ProjectService.create_project` (or equivalent agreed convention) - [ ] `PlanService.switch_to_plan` is renamed to `PlanService.get_plan_by_name` (or equivalent agreed convention) - [ ] All other services in `src/cleveragents/application/services/` are audited and refactored to follow the new convention - [ ] Method signatures for similar operations (e.g., listing, filtering) are consistent across services - [ ] All callers of renamed methods are updated - [ ] All existing tests pass after the refactor - [ ] No public API regressions are introduced ## Subtasks - [ ] Audit all service classes in `src/cleveragents/application/services/` and document current naming inconsistencies - [ ] Propose and agree on a unified naming convention (e.g., `create_*`, `get_*`, `list_*`, `delete_*`) - [ ] Rename `ProjectService.initialize_project` → `create_project` (or agreed name) - [ ] Rename `PlanService.switch_to_plan` → `get_plan_by_name` (or agreed name) - [ ] Audit and align method signatures for listing/filtering operations across all services - [ ] Update all callers of renamed/refactored methods throughout the codebase - [ ] Run full test suite and fix any failures - [ ] Update any relevant documentation or docstrings ## Definition of Done This issue should be closed when: - All service classes in `src/cleveragents/application/services/` follow a consistent, documented naming convention - All method signatures for similar operations are consistent - All callers are updated and the full test suite passes - No public API regressions exist --- **Automated by CleverAgents Bot** Supervisor: Architecture Guard | Agent: architecture-guard-worker --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.6.0 milestone 2026-04-14 03:26:10 +00:00
Author
Owner

Triage Decision: VERIFIED — MoSCoW/Should Have

Valid refactoring request: inconsistent API naming conventions and method signatures across the codebase create confusion and maintenance burden. Unifying these would improve code quality and developer experience.

This is a Should Have improvement — important for maintainability but not blocking core functionality. Assigning to v3.6.0 (Advanced Concepts & Deferred Features).

Priority/Medium — Code quality improvement, not a blocker.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Triage Decision: VERIFIED — MoSCoW/Should Have** Valid refactoring request: inconsistent API naming conventions and method signatures across the codebase create confusion and maintenance burden. Unifying these would improve code quality and developer experience. This is a Should Have improvement — important for maintainability but not blocking core functionality. Assigning to v3.6.0 (Advanced Concepts & Deferred Features). **Priority/Medium** — Code quality improvement, not a blocker. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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#8885
No description provided.