From 3fd6766dd24302c5a6f73670de8f3661c6bbc868 Mon Sep 17 00:00:00 2001
From: CleverThis <hal9000@cleverthis.com>
Date: Wed, 8 Apr 2026 13:16:01 +0000
Subject: [PATCH] docs: address review feedback for plan lifecycle showcase

---
 .../cli-tools/action-and-plan-management.md   | 21 ++++++++++++-------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/docs/showcase/cli-tools/action-and-plan-management.md b/docs/showcase/cli-tools/action-and-plan-management.md
index d3d1a4ef7..399879497 100644
--- a/docs/showcase/cli-tools/action-and-plan-management.md
+++ b/docs/showcase/cli-tools/action-and-plan-management.md
@@ -61,6 +61,8 @@ agents plan apply <plan-id>     ← writes changes to disk
 Plan (phase: apply, state: applied) ← terminal
 ```
 
+> **Note:** The lifecycle is not strictly linear — plans can revert from Execute or Apply back to Strategize when constraints (such as the `constrained` state) require reassessment.
+
 ---
 
 ## Step-by-Step Walkthrough
@@ -479,19 +481,20 @@ $ agents plan list
 ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┓
 ┃ ID                         ┃ Name                                   ┃ Phase      ┃ State    ┃ Action                 ┃ Invaria… ┃ Projects           ┃ Updated            ┃ Elapsed       ┃
 ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━┩
-│ 01KNKJZ44ES00VT8JTRKX1HEQA │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ (none)             │ 2026-04-07 09:04   │ 00:00:50      │
 │ 01KNKJZ424C48388RWHW3KY5QZ │ local/architecture-review-01knkjz4    │ strategize │ queued   │ local/architecture-re… │ 0        │ local/my-webapp    │ 2026-04-07 09:04   │ 00:00:50      │
 │ 01KNKK0MKCDXGP8Z3PZ88S5GGZ │ local/security-audit-01knkk0m         │ strategize │ queued   │ local/security-audit   │ 1        │ local/my-webapp    │ 2026-04-07 09:05   │ 00:00:00      │
 └────────────────────────────┴────────────────────────────────────────┴────────────┴──────────┴────────────────────────┴──────────┴────────────────────┴────────────────────┴───────────────┘
 ╭────────────────────────────────── Summary ───────────────────────────────────╮
-│ Total: 3                                                                     │
+│ Total: 2                                                                     │
 │ Processing: 0                                                                │
 │ Completed: 0                                                                 │
 │ Errored: 0                                                                   │
 ╰──────────────────────────────────────────────────────────────────────────────╯
-✓ OK 3 plans listed
+✓ OK 2 plans listed
 ```
 
+> **Tip:** This walkthrough concentrates on plan creation and lifecycle inspection. The `agents plan execute` and `agents plan apply` commands are covered in dedicated execution/apply showcases.
+
 ---
 
 ### Step 13: Filter plans by phase, state, and action
@@ -620,7 +623,7 @@ $ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json
 ### Step 16: Cancel a plan
 
 ```bash
-$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA
+$ agents plan cancel 01KNKJZ424C48388RWHW3KY5QZ
 ```
 
 **Output:**
@@ -662,7 +665,7 @@ local/security-audit
 
 # Count queued plans
 $ agents plan list --state queued --format json | jq '.data | length'
-3
+2
 
 # Get all plan IDs for a specific action
 $ agents plan list --action local/security-audit --format json \
@@ -681,6 +684,7 @@ $ agents plan list --format json | jq '.data[] | select(.state == "errored") | .
 
 | Phase | Description |
 |---|---|
+| `action` | Reusable template phase — transitions to Strategize via `agents plan use` |
 | `strategize` | AI creates an execution strategy (decisions tree) |
 | `execute` | AI executes the strategy, generating a ChangeSet |
 | `apply` | ChangeSet is written to disk |
@@ -691,7 +695,8 @@ $ agents plan list --format json | jq '.data[] | select(.state == "errored") | .
 |---|---|
 | `queued` | Waiting to be processed |
 | `processing` | Currently being processed by an actor |
-| `complete` | Phase completed successfully |
+| `complete` | Phase completed successfully (Strategize/Execute phases) |
+| `constrained` | Apply cannot proceed within current constraints — may revert to Strategize |
 | `applied` | Changes written to disk (terminal) |
 | `cancelled` | Cancelled by user (terminal) |
 | `errored` | Failed with an error (recoverable via `plan resume`) |
@@ -772,7 +777,7 @@ $ agents plan use local/security-audit local/my-webapp \
 
 # 12. List all plans
 $ agents plan list
-# → Table: 3 plans + Summary panel
+# → Table: 2 plans + Summary panel
 
 # 13. Filter plans
 $ agents plan list --phase strategize
@@ -788,7 +793,7 @@ $ agents plan status 01KNKJZ424C48388RWHW3KY5QZ --format json
 # → JSON envelope with full plan data
 
 # 16. Cancel a plan
-$ agents plan cancel 01KNKJZ44ES00VT8JTRKX1HEQA
+$ agents plan cancel 01KNKJZ424C48388RWHW3KY5QZ
 # → ✓ Plan cancelled: local/architecture-review-01knkjz4
 ```
 </details>