Epic: Legacy CLI command removal and full verification of CLI interface and workflows #4182

Open
opened 2026-04-06 18:44:00 +00:00 by CoreRasurae · 2 comments
Member

Metadata

  • Commit Message: feat(cli): complete legacy/v3 separation with clear help grouping and full verification
  • Branch: epic/legacy-v3-cli-separation

Background and Context

CleverAgents supports two fundamentally incompatible plan lifecycle modes that coexist in the same codebase:

  1. Legacy Workflow (agents tellagents build → apply): Human-readable plan names, simple flow, deprecated
  2. V3 Workflow (agents plan useagents plan executeagents plan apply): ULID-based plan IDs, full decision tree, current architecture

This epic addresses a critical architectural gap: while the two workflows are explicitly incompatible (by design) and use separate storage systems, the CLI help output, error messages, specification documentation, and test coverage do not adequately reflect this separation. Users can easily confuse the two modes, and developers may accidentally mix them without clear warning.

Current State

Problems:

  • agents plan --help shows v3 commands with no indication of legacy alternatives or incompatibility
  • Legacy commands exist as top-level agents tell, agents build, etc. with deprecation warnings only on execution, not in help
  • docs/specification.md documents only v3 commands; legacy commands are absent
  • Error messages acknowledge incompatibility but only appear on failure (not in help)
  • Test coverage for legacy workflow is incomplete; no tests verify help output separation
  • No migration guide from legacy to v3 exists in specification
  • Architectural rationale for keeping both modes is not documented
  • Help output uses Typer's default formatting with no visual distinction between workflows

Impact:

  • Users experience confusion when help text doesn't clearly indicate deprecated status
  • New contributors don't understand why two separate systems exist
  • Specification is incomplete and doesn't serve as authoritative source for CLI structure
  • Difficult to evolve either workflow without breaking the other

Expected Behavior

  1. Clear CLI Help Grouping

    • agents plan --help shows one visually identified section: "V3 Plan Lifecycle"
    • The section uses Rich panels or similar visual separation
  2. Complete Specification Documentation

    • Migration guide provides step-by-step instructions for moving from legacy to v3
  3. Clear Error Handling

    • Error messages should only refer to V3 pan lifecycle

Acceptance Criteria

  • CLI help output (agents plan --help) clearly removes all legacy commands, while V3 commands are in a visually identified group with appropriate labeling
  • A migration guide exists in Legacy_to_V3_Guide.md providing clear steps from legacy to v3
  • All help output text is tested (Behave): sections present, labels correct, deprecation messages visible
  • All error messages tested when mixing modes (Behave): appropriate guidance provided
  • Legacy workflow has complete end-to-end test coverage (Behave + Robot)
  • V3 workflow has complete end-to-end test coverage (Behave + Robot)
  • Test coverage for CLI module remains >=97%
  • No regressions in legacy command functionality
  • Documentation is updated to reflect the separation (README, spec, guides)

Child Issues

This epic will be broken down into the following child issues:

  1. CLI Help Output Separation and Grouping (highest priority)

    • Refactor plan.py help rendering to use Rich panels
    • Separate legacy and v3 command groups with visual distinction
    • Add status labels and deprecation notices
    • Related to: #4181
  2. Specification and Architecture Documentation

    • Write legacy to v3 migration guide
  3. Error Message Improvements

    • Enhance error messages by removing all references to legacy commands
    • Reference help output
  4. V3 Workflow Test Coverage Completion

    • Audit existing v3 test coverage
    • Add missing Behave scenarios
    • Add missing Robot Framework integration tests
    • Ensure all phase transitions tested
  5. Help Output and Error Message Testing

    • Test help output contains expected sections and labels
  6. Documentation Updates

    • Link to migration guide from main documentation

Definition of Done

This Epic is complete when:

  • All child issues above are created, verified, and assigned to a developer
  • All child issues are moved to State/In progress and completed
  • All child issues are merged to master as pull requests
  • CLI help output clearly removes legacy and properly documents v3 commands with clear visual identification
  • A migration guide from legacy to v3 exists and is linked from specification
  • All acceptance criteria above are satisfied
  • Test coverage for CLI module is >=97%
  • All Behave and Robot tests pass
  • Code review has been completed and all feedback addressed
  • Documentation is updated, current, and reflects the separation

Supporting Information

Key files involved:

  • src/cleveragents/cli/commands/plan.py (legacy commands: lines 844-1319; v3 commands: lines 1598-4000; error messages: lines 56-72)
  • src/cleveragents/cli/formatting.py (help rendering and formatting logic)
  • docs/specification.md (CLI Commands section: lines 199-368; glossary)
  • docs/adr/ADR-021-cli-and-output-rendering.md (current command structure definition)
  • CONTRIBUTING.md (project guidelines for all layers)

Related issues:

  • #4181: CLI command structure lacks separation and documentation (specific task capturing this gap)

Architecture context:

  • Legacy and v3 use entirely separate storage systems (different database tables/structures)
  • Plans cannot be mixed between modes (enforced at runtime)
  • Error message at plan.py lines 56-72 already acknowledges incompatibility
  • Deprecation warnings exist in legacy command help docstrings but aren't rendered in help output

Relevant ADRs:

  • ADR-021: CLI and Output Rendering (defines command structure and help rendering)
  • ADR-001: Layered Architecture (Presentation layer contains CLI)

Epic Scope Notes

In Scope:

  • CLI help output improvements and visual separation
  • Specification documentation updates
  • Error message improvements
  • Migration guidance documentation

Out of Scope (separate efforts):

  • Server mode A2A protocol work (separate epic #933)

Subtasks

  • Create child issue: Remove all legacy commands from the codebase and keep only V3 CLI commands
  • Assign all child issues to appropriate developers with milestones
  • Review and verify all child issues before starting work
  • Monitor child issue progress and coordinate cross-cutting concerns
  • Verify all acceptance criteria are met upon completion
## Metadata - **Commit Message**: `feat(cli): complete legacy/v3 separation with clear help grouping and full verification` - **Branch**: `epic/legacy-v3-cli-separation` ## Background and Context CleverAgents supports two fundamentally incompatible plan lifecycle modes that coexist in the same codebase: 1. **Legacy Workflow** (`agents tell` → `agents build` → apply): Human-readable plan names, simple flow, deprecated 2. **V3 Workflow** (`agents plan use` → `agents plan execute` → `agents plan apply`): ULID-based plan IDs, full decision tree, current architecture This epic addresses a critical architectural gap: while the two workflows are explicitly incompatible (by design) and use separate storage systems, the CLI help output, error messages, specification documentation, and test coverage do not adequately reflect this separation. Users can easily confuse the two modes, and developers may accidentally mix them without clear warning. ### Current State **Problems:** - `agents plan --help` shows v3 commands with no indication of legacy alternatives or incompatibility - Legacy commands exist as top-level `agents tell`, `agents build`, etc. with deprecation warnings only on execution, not in help - docs/specification.md documents only v3 commands; legacy commands are absent - Error messages acknowledge incompatibility but only appear on failure (not in help) - Test coverage for legacy workflow is incomplete; no tests verify help output separation - No migration guide from legacy to v3 exists in specification - Architectural rationale for keeping both modes is not documented - Help output uses Typer's default formatting with no visual distinction between workflows **Impact:** - Users experience confusion when help text doesn't clearly indicate deprecated status - New contributors don't understand why two separate systems exist - Specification is incomplete and doesn't serve as authoritative source for CLI structure - Difficult to evolve either workflow without breaking the other ## Expected Behavior 1. **Clear CLI Help Grouping** - `agents plan --help` shows one visually identified section: "V3 Plan Lifecycle" - The section uses Rich panels or similar visual separation 2. **Complete Specification Documentation** - Migration guide provides step-by-step instructions for moving from legacy to v3 3. **Clear Error Handling** - Error messages should only refer to V3 pan lifecycle ## Acceptance Criteria - [ ] CLI help output (`agents plan --help`) clearly removes all legacy commands, while V3 commands are in a visually identified group with appropriate labeling - [ ] A migration guide exists in Legacy_to_V3_Guide.md providing clear steps from legacy to v3 - [ ] All help output text is tested (Behave): sections present, labels correct, deprecation messages visible - [ ] All error messages tested when mixing modes (Behave): appropriate guidance provided - [ ] Legacy workflow has complete end-to-end test coverage (Behave + Robot) - [ ] V3 workflow has complete end-to-end test coverage (Behave + Robot) - [ ] Test coverage for CLI module remains >=97% - [ ] No regressions in legacy command functionality - [ ] Documentation is updated to reflect the separation (README, spec, guides) ## Child Issues This epic will be broken down into the following child issues: 1. **CLI Help Output Separation and Grouping** (highest priority) - Refactor plan.py help rendering to use Rich panels - Separate legacy and v3 command groups with visual distinction - Add status labels and deprecation notices - Related to: #4181 2. **Specification and Architecture Documentation** - Write legacy to v3 migration guide 3. **Error Message Improvements** - Enhance error messages by removing all references to legacy commands - Reference help output 4. **V3 Workflow Test Coverage Completion** - Audit existing v3 test coverage - Add missing Behave scenarios - Add missing Robot Framework integration tests - Ensure all phase transitions tested 6. **Help Output and Error Message Testing** - Test help output contains expected sections and labels 7. **Documentation Updates** - Link to migration guide from main documentation ## Definition of Done This Epic is complete when: - All child issues above are created, verified, and assigned to a developer - All child issues are moved to State/In progress and completed - All child issues are merged to master as pull requests - CLI help output clearly removes legacy and properly documents v3 commands with clear visual identification - A migration guide from legacy to v3 exists and is linked from specification - All acceptance criteria above are satisfied - Test coverage for CLI module is >=97% - All Behave and Robot tests pass - Code review has been completed and all feedback addressed - Documentation is updated, current, and reflects the separation ## Supporting Information **Key files involved:** - `src/cleveragents/cli/commands/plan.py` (legacy commands: lines 844-1319; v3 commands: lines 1598-4000; error messages: lines 56-72) - `src/cleveragents/cli/formatting.py` (help rendering and formatting logic) - `docs/specification.md` (CLI Commands section: lines 199-368; glossary) - `docs/adr/ADR-021-cli-and-output-rendering.md` (current command structure definition) - `CONTRIBUTING.md` (project guidelines for all layers) **Related issues:** - #4181: CLI command structure lacks separation and documentation (specific task capturing this gap) **Architecture context:** - Legacy and v3 use entirely separate storage systems (different database tables/structures) - Plans cannot be mixed between modes (enforced at runtime) - Error message at plan.py lines 56-72 already acknowledges incompatibility - Deprecation warnings exist in legacy command help docstrings but aren't rendered in help output **Relevant ADRs:** - ADR-021: CLI and Output Rendering (defines command structure and help rendering) - ADR-001: Layered Architecture (Presentation layer contains CLI) ## Epic Scope Notes **In Scope:** - CLI help output improvements and visual separation - Specification documentation updates - Error message improvements - Migration guidance documentation **Out of Scope (separate efforts):** - Server mode A2A protocol work (separate epic #933) --- ## Subtasks - [ ] Create child issue: Remove all legacy commands from the codebase and keep only V3 CLI commands - [ ] Assign all child issues to appropriate developers with milestones - [ ] Review and verify all child issues before starting work - [ ] Monitor child issue progress and coordinate cross-cutting concerns - [ ] Verify all acceptance criteria are met upon completion
Author
Member

Epic Structure and Child Issue Planning

This epic (#4182) provides the overarching vision for complete legacy/v3 separation and verification. The related issue #4181 is a specific task that addresses the most immediate problem identified: CLI help output lacks clear separation and documentation.

Relationship Between Issues

  • #4182 (This Epic): Comprehensive, multi-faceted work covering:

    • CLI help improvements
    • Specification documentation
    • Test infrastructure
    • Error handling
    • Migration guidance
    • Architecture documentation
  • #4181 (Specific Task): Focused on the primary UX problem:

    • Implement CLI help grouping using Rich panels
    • Add deprecation/status labels
    • Reference migration guide
    • Can proceed relatively independently

Implementation Strategy

Phase 1 (High Priority):

  1. Verify and triage this epic (#4182)
  2. Create child issues from the list in the epic description
  3. Start with highest-priority child: "CLI Help Output Separation and Grouping" (related to #4181)

Phase 2 (Specification & Documentation):

  1. Update specification with legacy/v3 CLI structures
  2. Create ADR for architectural rationale
  3. Write migration guide

Phase 3 (Testing & Verification):

  1. Add comprehensive test coverage for both workflows
  2. Verify help output rendering
  3. Test error messages when mixing modes

Phase 4 (Integration):

  1. Ensure all changes work together
  2. Verify documentation consistency
  3. Final QA before marking epic complete

Notes for Maintainer

  • This epic is interdependent with specification/documentation work — prioritize clarity and consistency
  • Help output work (#4181) can begin immediately as it's primarily a CLI concern
  • Test coverage work should happen in parallel with help/documentation improvements
  • Migration guide should reference the final help output structure (helps with internal consistency)

Labels: State/Unverified, Type/Epic, Priority/Backlog, needs feedback | Status: Awaiting triage and child issue creation

## Epic Structure and Child Issue Planning This epic (#4182) provides the overarching vision for complete legacy/v3 separation and verification. The related issue #4181 is a **specific task** that addresses the most immediate problem identified: **CLI help output lacks clear separation and documentation**. ### Relationship Between Issues - **#4182 (This Epic)**: Comprehensive, multi-faceted work covering: - CLI help improvements - Specification documentation - Test infrastructure - Error handling - Migration guidance - Architecture documentation - **#4181 (Specific Task)**: Focused on the primary UX problem: - Implement CLI help grouping using Rich panels - Add deprecation/status labels - Reference migration guide - Can proceed relatively independently ### Implementation Strategy **Phase 1 (High Priority):** 1. Verify and triage this epic (#4182) 2. Create child issues from the list in the epic description 3. Start with highest-priority child: "CLI Help Output Separation and Grouping" (related to #4181) **Phase 2 (Specification & Documentation):** 1. Update specification with legacy/v3 CLI structures 2. Create ADR for architectural rationale 3. Write migration guide **Phase 3 (Testing & Verification):** 1. Add comprehensive test coverage for both workflows 2. Verify help output rendering 3. Test error messages when mixing modes **Phase 4 (Integration):** 1. Ensure all changes work together 2. Verify documentation consistency 3. Final QA before marking epic complete --- ## Notes for Maintainer - This epic is interdependent with specification/documentation work — prioritize clarity and consistency - Help output work (#4181) can begin immediately as it's primarily a CLI concern - Test coverage work should happen in parallel with help/documentation improvements - Migration guide should reference the final help output structure (helps with internal consistency) **Labels**: State/Unverified, Type/Epic, Priority/Backlog, needs feedback | **Status**: Awaiting triage and child issue creation
CoreRasurae changed title from Epic: Legacy and v3 clean separation and full verification of both CLI interfaces and workflows to Epic: Legacy CLI command removal and full verification of CLI interface and workflows 2026-04-07 16:15:01 +00:00
Owner

Child Issues Created for Epic #4182

In response to the planning request, the following child issues have been created and linked to this epic:

Existing Child Issue (pre-existing)

  • #4181 — CLI command structure still has legacy and v3 plan lifecycles - removal of legacy CLI commands

Newly Created Child Issues

# Issue Type Priority Status
1 #4376 — Write legacy-to-v3 migration guide and update specification documentation Task Medium Unverified
2 #4377 — Remove legacy command references from error messages and standardize V3-only error guidance Task Medium Unverified
3 #4378 — Add complete V3 workflow end-to-end test coverage (Behave + Robot Framework) Testing Medium Unverified
4 #4379 — Add Behave scenarios verifying CLI help output sections and V3-only command structure Testing Medium Unverified
5 #4380 — Update README and specification to link migration guide and reflect V3-only CLI structure Task Medium Unverified

Dependency Chain

#4181 (CLI help output separation)
  ├── blocks → #4379 (help output testing)
  └── blocks → #4380 (docs updates)

#4376 (migration guide)
  └── blocks → #4380 (docs updates)

All child issues block → #4182 (this epic)
  1. Phase 1 (Parallel): #4181 (CLI help) + #4376 (migration guide) + #4377 (error messages)
  2. Phase 2 (After Phase 1): #4378 (V3 test coverage) + #4379 (help output tests)
  3. Phase 3 (After Phase 2): #4380 (documentation updates)

All issues are in State/Unverified and need maintainer verification before implementation begins.


Automated by CleverAgents Bot
Supervisor: Product Builder | Agent: epic-planner

## Child Issues Created for Epic #4182 In response to the planning request, the following child issues have been created and linked to this epic: ### Existing Child Issue (pre-existing) - [x] #4181 — CLI command structure still has legacy and v3 plan lifecycles - removal of legacy CLI commands ### Newly Created Child Issues | # | Issue | Type | Priority | Status | |---|-------|------|----------|--------| | 1 | #4376 — Write legacy-to-v3 migration guide and update specification documentation | Task | Medium | Unverified | | 2 | #4377 — Remove legacy command references from error messages and standardize V3-only error guidance | Task | Medium | Unverified | | 3 | #4378 — Add complete V3 workflow end-to-end test coverage (Behave + Robot Framework) | Testing | Medium | Unverified | | 4 | #4379 — Add Behave scenarios verifying CLI help output sections and V3-only command structure | Testing | Medium | Unverified | | 5 | #4380 — Update README and specification to link migration guide and reflect V3-only CLI structure | Task | Medium | Unverified | ### Dependency Chain ``` #4181 (CLI help output separation) ├── blocks → #4379 (help output testing) └── blocks → #4380 (docs updates) #4376 (migration guide) └── blocks → #4380 (docs updates) All child issues block → #4182 (this epic) ``` ### Recommended Implementation Order 1. **Phase 1 (Parallel)**: #4181 (CLI help) + #4376 (migration guide) + #4377 (error messages) 2. **Phase 2 (After Phase 1)**: #4378 (V3 test coverage) + #4379 (help output tests) 3. **Phase 3 (After Phase 2)**: #4380 (documentation updates) All issues are in `State/Unverified` and need maintainer verification before implementation begins. --- **Automated by CleverAgents Bot** Supervisor: Product Builder | Agent: epic-planner
HAL9000 added this to the v3.5.0 milestone 2026-04-08 17:54:17 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on
Reference
cleveragents/cleveragents-core#4182
No description provided.