feat(cli): write legacy-to-v3 migration guide and update specification documentation #4376

Open
opened 2026-04-08 11:24:45 +00:00 by HAL9000 · 0 comments
Owner

Metadata

  • Commit Message: feat(cli): write legacy-to-v3 migration guide and update specification documentation
  • Branch: feature/legacy-v3-cli-migration-guide
  • Parent Epic: #4182

Background and Context

Epic #4182 identifies that the CleverAgents specification and documentation do not adequately document the separation between the legacy workflow (agents tellagents build) and the V3 workflow (agents plan useagents plan executeagents plan apply). Users and contributors lack a clear migration path from legacy to V3.

Expected Behavior

A comprehensive migration guide exists at docs/Legacy_to_V3_Guide.md that:

  • Explains the architectural differences between legacy and V3 workflows
  • Provides step-by-step migration instructions
  • Maps legacy commands to their V3 equivalents
  • Documents why the two systems are incompatible (separate storage systems)
  • Is linked from docs/specification.md and README.md

Acceptance Criteria

  • docs/Legacy_to_V3_Guide.md exists with complete migration instructions
  • Guide covers all legacy commands and their V3 equivalents
  • Guide explains the architectural rationale for keeping both modes
  • docs/specification.md CLI Commands section references the migration guide
  • README.md links to the migration guide
  • ADR documenting the legacy/V3 separation rationale is created or updated

Supporting Information

  • Key files: docs/specification.md (CLI Commands section: lines 199–368), docs/adr/ADR-021-cli-and-output-rendering.md
  • Legacy commands: agents tell, agents build, agents apply (top-level)
  • V3 commands: agents plan use, agents plan execute, agents plan apply
  • Related: #4181 (CLI help output separation), #4182 (parent epic)

Subtasks

  • Audit all legacy commands in src/cleveragents/cli/commands/ and document them
  • Write docs/Legacy_to_V3_Guide.md with step-by-step migration instructions
  • Map each legacy command to its V3 equivalent
  • Document the storage system differences (why mixing is impossible)
  • Update docs/specification.md to reference the migration guide
  • Update README.md to link to the migration guide
  • Tests (Behave): Add scenario verifying migration guide file exists and has required sections
  • Run nox (all default sessions), fix any errors
  • Verify coverage >= 97% via nox -s coverage_report

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • docs/Legacy_to_V3_Guide.md exists with complete, accurate migration instructions.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage >= 97%.

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

## Metadata - **Commit Message**: `feat(cli): write legacy-to-v3 migration guide and update specification documentation` - **Branch**: `feature/legacy-v3-cli-migration-guide` - **Parent Epic**: #4182 ## Background and Context Epic #4182 identifies that the CleverAgents specification and documentation do not adequately document the separation between the legacy workflow (`agents tell` → `agents build`) and the V3 workflow (`agents plan use` → `agents plan execute` → `agents plan apply`). Users and contributors lack a clear migration path from legacy to V3. ## Expected Behavior A comprehensive migration guide exists at `docs/Legacy_to_V3_Guide.md` that: - Explains the architectural differences between legacy and V3 workflows - Provides step-by-step migration instructions - Maps legacy commands to their V3 equivalents - Documents why the two systems are incompatible (separate storage systems) - Is linked from `docs/specification.md` and `README.md` ## Acceptance Criteria - [ ] `docs/Legacy_to_V3_Guide.md` exists with complete migration instructions - [ ] Guide covers all legacy commands and their V3 equivalents - [ ] Guide explains the architectural rationale for keeping both modes - [ ] `docs/specification.md` CLI Commands section references the migration guide - [ ] `README.md` links to the migration guide - [ ] ADR documenting the legacy/V3 separation rationale is created or updated ## Supporting Information - **Key files**: `docs/specification.md` (CLI Commands section: lines 199–368), `docs/adr/ADR-021-cli-and-output-rendering.md` - **Legacy commands**: `agents tell`, `agents build`, `agents apply` (top-level) - **V3 commands**: `agents plan use`, `agents plan execute`, `agents plan apply` - **Related**: #4181 (CLI help output separation), #4182 (parent epic) ## Subtasks - [ ] Audit all legacy commands in `src/cleveragents/cli/commands/` and document them - [ ] Write `docs/Legacy_to_V3_Guide.md` with step-by-step migration instructions - [ ] Map each legacy command to its V3 equivalent - [ ] Document the storage system differences (why mixing is impossible) - [ ] Update `docs/specification.md` to reference the migration guide - [ ] Update `README.md` to link to the migration guide - [ ] Tests (Behave): Add scenario verifying migration guide file exists and has required sections - [ ] Run `nox` (all default sessions), fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - `docs/Legacy_to_V3_Guide.md` exists with complete, accurate migration instructions. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional details. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: Product Builder | Agent: epic-planner
HAL9000 added this to the v3.5.0 milestone 2026-04-08 17:43:07 +00:00
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.

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