cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity
Files
1b12af27651df4dfd864defc49513d8ae83c8e5a
cleveragents-core/docs/Legacy_to_V3_Guide.md
T
CoreRasurae cc24d8c8ac fix(cli): remove legacy plan commands from help output 
Completely removed all legacy plan commands from the CLI:
    - Removed tell, build, new, current, cd, continue CLI commands
    - Removed programmatic wrapper functions (tell_command, build_command, etc.)
    - Removed legacy deprecation message
    - Updated help text to indicate V3 Plan Lifecycle exclusively
    - Removed stale references to tell/build in help output and command validation

    Removes the legacy 'tell' and 'build' CLI shortcuts from main.py:
    - Removed echo lines advertising tell/build commands
    - Removed tell/build from valid_cmds list
    - Removed tell/build from _LIGHTWEIGHT_COMMANDS frozenset
    - These dead entries were preventing helpful error messages

    Test infrastructure improvements:
    - Event bus exception test: Patch the module-level logger during emit() so that
      structlog.testing.capture_logs() can capture the logs. Without patching, the
      module-level logger created at import time is not captured by the context manager.
    - Session create/list commands: Suppress cleveragents.mcp logger to CRITICAL level
      during JSON/YAML output formatting to prevent health check warnings with ANSI codes
      from being written to stdout before JSON output, which breaks JSON parsing.
    - Extended plan_cli_coverage_boost with scenarios for estimation_result,
      invariants, execution_environment, validation_summary, and checkpoint
      coverage in _plan_spec_dict

    Documentation:
    - Created docs/Legacy_to_V3_Guide.md with comprehensive migration instructions
    - Updated CONTRIBUTING.md to document removal of legacy workflow
    - Updated CHANGELOG.md to reference issue #4181 instead of PR #10800

ISSUES CLOSED: #4181
2026-05-05 02:01:49 +00:00

7.8 KiB
Raw Blame History

Migration Guide: Legacy to V3 Plan Lifecycle

Overview

CleverAgents has transitioned from a legacy plan workflow to the V3 Plan Lifecycle architecture. The legacy commands (agents tell, agents build, agents apply) have been permanently removed as of v3.5.0.

This guide helps you migrate from the legacy workflow to the V3 workflow.

Why the Change?

The V3 Plan Lifecycle provides:

  • ULID-based identifiers for reliable plan tracking across sessions
  • Explicit phase management (Strategize → Execute → Apply) with decision trees
  • Hierarchical subplans for decomposing large tasks
  • Checkpoint and rollback support for safe, reversible execution
  • Comprehensive CLI support with detailed plan inspection commands

The legacy workflow was limited to simple name-based plans with linear execution and lacked these architectural improvements.

Migration Table

Activity Legacy Command V3 Command Notes
Create a plan agents tell -n "plan name" "Instructions..." agents plan use <action> <project> V3 returns a ULID identifier
Execute a plan agents build agents plan execute <PLAN_ID> Must use ULID, not plan name
Apply changes agents apply my-plan agents plan apply <PLAN_ID> Must use ULID, not plan name
List plans agents list (implicit) agents plan list Shows ULID-based plans
Show current plan agents current (implicit) agents plan status [PLAN_ID] Shows detailed plan state and decisions
Continue working agents continue agents plan prompt <PLAN_ID> Send guidance during execution
Show history Not available agents plan tree <PLAN_ID> Shows decision tree
Rollback Not available agents plan rollback <PLAN_ID> <checkpoint> Requires checkpoint support

Step-by-Step Migration

Before: Legacy Workflow

# 1. Create a plan with text instructions
agents tell -n "64-bit port plan" "Analyze the codebase and create a plan to add 64-bit support to the build system"

# 2. Build the plan (not executing — just strategizing)
agents build

# 3. Review and then apply
agents apply 64-bit port plan

After: V3 Workflow

# 1. Create a V3 plan using an action template
agents plan use local/code-enhancement my-project
# Output: Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J

# 2. Execute the plan (strategize + execute phases)
agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J

# 3. Review the decision tree and artifacts
agents plan tree 01HXM8C2ZK4Q7C2B3F2R4VYV6J
agents plan artifacts 01HXM8C2ZK4Q7C2B3F2R4VYV6J

# 4. Apply the changes (Execute → Apply phase)
agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J

Key Differences

Identifiers

Legacy: Human-readable plan names

agents tell -n "my-plan" "Instructions..."
agents build        # Works on the current plan
agents apply my-plan  # Reference by name

V3: ULID identifiers

agents plan use local/my-action my-project
# Returns: 01HXM8C2ZK4Q7C2B3F2R4VYV6J

agents plan execute 01HXM8C2ZK4Q7C2B3F2R4VYV6J  # Must use ULID
agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J    # Must use ULID

Phase Management

Legacy: No explicit phases

  • agents tell created a plan
  • agents build executed it
  • agents apply committed changes

V3: Explicit four-phase lifecycle

  1. Action — Plan template selection
  2. Strategize — Decision tree generation (read-only)
  3. Execute — Tool invocation and changes (sandboxed)
  4. Apply — Commit changes to project

Planning

Legacy: Free-form text instructions

agents tell "Devise a plan to add 64-bit support..."

V3: Action templates + projects

agents plan use local/code-enhancement my-project

This provides structured planning with type-safe arguments and invariant constraints.

Inspection

Legacy: Limited visibility

  • No way to see decision history
  • No checkpoint support
  • No rollback capability

V3: Rich inspection capabilities

agents plan tree <PLAN_ID>              # Decision tree with context
agents plan artifacts <PLAN_ID>         # Sandbox artifacts and outputs
agents plan status <PLAN_ID>            # Current phase and metrics
agents plan explain <PLAN_ID> <decision-id>  # Explain specific decision
agents plan errors <PLAN_ID>            # Error decisions and recovery hints

Command Mapping Reference

Legacy V3 Replacement Purpose
agents tell -n "name" "text" agents plan use <action> <project> Create plan
agents current agents plan status [PLAN_ID] Show current plan
agents list agents plan list List all plans
agents build agents plan execute <PLAN_ID> Execute plan
agents apply <name> agents plan apply <PLAN_ID> Apply changes
agents continue agents plan prompt <PLAN_ID> Send guidance
(not available) agents plan tree <PLAN_ID> View decision tree
(not available) agents plan rollback <PLAN_ID> <checkpoint> Rollback execution
(not available) agents plan correct <PLAN_ID> <decision-id> Correct decision

Troubleshooting

"Plan not found" with a plan name

Problem:

Error: Plan 'my-plan' not found.

Cause: You are using a legacy plan name with a V3 command. V3 commands require ULID identifiers.

Solution: Use agents plan list to see your plans with their ULIDs, then reference the ULID:

agents plan list           # Find your plan's ULID
agents plan status 01HXM8C2ZK4Q7C2B3F2R4VYV6J

"Command not found" (tell, build, continue, etc.)

Problem:

Error: No such command: tell

Cause: Legacy commands have been removed. You must use V3 commands.

Solution: Refer to the migration table above for the equivalent V3 command.

agents tell vs agents session tell — name collision

Important: The legacy agents tell command (which created plans) has been permanently removed. A new agents session tell command exists under the session subcommand group, but it serves a completely different purpose:

Command Purpose Status
agents tell (legacy) Created a plan from text instructions Removed
agents session tell Sends a message to an existing session Active (V3)

If you previously used agents tell to create plans, you must now use agents plan use <action> <project>. The agents session tell command is only for sending messages to sessions created via agents session create.

agents tell vs agents session tell — name collision

Important: The legacy agents tell command (which created plans) has been permanently removed. A new agents session tell command exists under the session subcommand group, but it serves a completely different purpose:

Command Purpose Status
agents tell (legacy) Created a plan from text instructions Removed
agents session tell Sends a message to an existing session Active (V3)

If you previously used agents tell to create plans, you must now use agents plan use <action> <project>. The agents session tell command is only for sending messages to sessions created via agents session create.

Resources

  • Specification: See docs/specification.md for the complete V3 Plan Lifecycle architecture
  • CLI Commands: Run agents plan --help for all V3 plan operations
  • Decision Correction: See docs/specification.md for selective subtree recomputation after plan correction
  • Actions: Create custom action templates for your workflows

Still Have Questions?

  • Run agents --help for CLI command overview
  • Run agents plan --help for plan-specific commands
  • Run agents plan <command> --help for detailed command documentation
  • Check issue #4181 for the legacy command removal discussion
Reference in New Issue View Git Blame Copy Permalink