# CLI Plan Workflow — CleverAgents Project

> ⚠️ Rules here override `cleverthis-guidelines`. Apply these exactly.

---

## Two Mutually Exclusive Systems

The CleverAgents CLI supports two plan workflow systems. **They cannot be
mixed under any circumstances.** Choosing a system commits you to it for the
entire lifecycle of that plan.

| Property | v3 (authoritative) | Legacy (deprecated) |
|----------|-------------------|---------------------|
| Status | ✅ Use this for all new work | ❌ Deprecated — do not start new work |
| Create | `agents plan use local/<action> <project>` | `agents tell -n "<name>" "<goal>"` |
| Execute | `agents plan execute <ULID>` | `agents build` |
| Apply | `agents plan apply <ULID>` | `agents apply <name>` |
| Identifier | ULID (26-char Crockford base32) | Human-readable name |
| Storage | `PlanLifecycleService` | `PlanService` (separate backend) |
| Warnings | None | Deprecation warnings emitted |

---

## v3 Workflow (Always Use This)

Per `docs/specification.md`, the v3 plan lifecycle is the authoritative workflow.
All new development uses v3 commands exclusively.

```bash
# Step 1: Create a v3 plan from an action template
agents plan use local/my-action my-project
# Output: Plan ID: 01HXM8C2ZK4Q7C2B3F2R4VYV6J

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

# Step 3: Apply the changes
agents plan apply 01HXM8C2ZK4Q7C2B3F2R4VYV6J
```

### ULID Format

v3 plan identifiers are **ULIDs** — 26-character Crockford base32 strings:

```
01HXM8C2ZK4Q7C2B3F2R4VYV6J
```

- 26 characters, uppercase
- Characters from the Crockford base32 alphabet (excludes I, L, O, U)
- Time-ordered (first 10 chars encode timestamp)
- Always start with a digit (0-9) or letter from the Crockford alphabet

If you see a human-readable name where you expect a ULID, you are using the
wrong workflow system.

---

## Legacy Workflow (Deprecated)

Legacy commands are deprecated and **will be removed** in a future version.
They emit deprecation warnings. Do not start new plans with legacy commands.
If you are maintaining existing legacy plans, use legacy commands exclusively
— do not mix:

```bash
# Legacy workflow (deprecated — emit deprecation warnings):
agents tell -n "my-plan" "Devise a plan to modernize the authentication layer"
agents build
agents apply my-plan
```

---

## Why They Cannot Be Mixed

The two systems use **completely separate storage backends**:

| Command | Reads from | Writes to |
|---------|-----------|-----------|
| `agents tell` | — | `PlanService` |
| `agents build` | `PlanService` | `PlanService` |
| `agents apply <name>` | `PlanService` | applies |
| `agents plan use` | — | `PlanLifecycleService` |
| `agents plan execute <ULID>` | `PlanLifecycleService` | `PlanLifecycleService` |
| `agents plan apply <ULID>` | `PlanLifecycleService` | applies |

A plan created with `agents tell` exists **only** in `PlanService`. It is
completely invisible to v3 commands, which query only `PlanLifecycleService`.

Additionally, v3 commands require ULIDs. Passing a human-readable name to
`agents plan execute` or `agents plan apply` is rejected with an explicit error.

---

## Error Diagnosis

### "Plan not found" with a name

```
Error: Plan 'my-legacy-plan' not found.

The v3 plan lifecycle expects a ULID identifier
(e.g., 01HXM8C2ZK4Q7C2B3F2R4VYV6J), not a plan name.

Possible causes:
  1. You created a plan with 'agents tell' (legacy workflow) and are
     trying to reference it with a v3 command. These workflows are
     incompatible and cannot be mixed — legacy plans exist only in the
     legacy storage system and are invisible to v3 commands.
  2. You referenced the wrong plan ID.
```

**Diagnosis:** You used `agents tell` to create the plan (legacy) and then
tried to reference it with `agents plan execute` (v3). These are incompatible.

**Resolution:**
- If the legacy plan still needs to be completed: use `agents build` and
  `agents apply <name>` exclusively for that plan.
- If starting fresh: create a new v3 plan with `agents plan use`.

### "Invalid ULID" error

You passed a human-readable name or malformed string to a v3 command.
v3 commands accept only valid 26-character Crockford base32 ULIDs.

---

## Migration from Legacy to v3

There is **no automatic migration path**. Legacy plans cannot be converted
to v3 plans.

To migrate manually:

1. Identify what the legacy plan was intended to accomplish.
2. Create a new v3 plan:
   ```bash
   agents plan use local/<action> <project>
   # Returns a new ULID — e.g. 01HXM8C2ZK4Q7C2B3F2R4VYV6J
   ```
3. Use v3 commands for all subsequent operations.

The legacy plan remains in `PlanService` — it does not need to be deleted.
Simply stop referencing it and use the new v3 ULID going forward.

---

## Backwards Compatibility Policy

Related note: this project has **no backwards compatibility before v3.0.0**:

- No migration guides for old configurations
- No compatibility shims
- No support for old data formats
- The v3 plan lifecycle is the authoritative system going forward
- Backwards compatibility work begins only at v3.0.0 and applies to the
  v3 system — not to legacy

The legacy plan workflow will be removed in a future major version.
