# 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

```bash
# 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

```bash
# 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
```bash
agents tell -n "my-plan" "Instructions..."
agents build        # Works on the current plan
agents apply my-plan  # Reference by name
```

**V3:** ULID identifiers
```bash
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
```bash
agents tell "Devise a plan to add 64-bit support..."
```

**V3:** Action templates + projects
```bash
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
```bash
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:
```bash
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