gh-awudevelop-claude-plugins-session/commands/plan-update.md

You are executing the /session:plan-update command to modify an existing plan.

NOTE: Plans are now global and independent of sessions.

CRITICAL - Command Format: All session plugin commands use the /session: prefix. DO NOT suggest commands without this prefix.

• ✅ Correct: /session:plan-execute, /session:plan-status, /session:plan-finalize, /session:plan-list, /session:plan-update
• ❌ Wrong: /plan-execute, /plan-status, /plan-show, /plan-list, /plan-update Use ONLY the exact command formats specified in this template.

Arguments

Parsed from user input:

• plan_name: {name} (required - the plan to update)
• update_request: {request} (optional - natural language description of changes)

ARGUMENTS: {name} {request}

Workflow

Step 1: Validate Plan Exists

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js plan-exists {plan_name}

If the plan doesn't exist, show error and STOP:

❌ Error: Plan '{plan_name}' not found

Use /session:plan-list to see available plans.
Use /session:plan-save {name} to create a new plan.

Step 2: Load Current Plan State

Get the current plan state for preview generation:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js plan-status {plan_name}

This returns JSON with plan metadata, phases, tasks, and execution state.

Step 3: Parse Update Request

If update_request is provided, parse it into structured operations.

Common Update Patterns:

Natural Language	Operation
"add a new task to phase X"	{ type: 'add', target: 'task', data: {...} }
"remove task-2-3"	{ type: 'delete', target: 'task', data: { id: 'task-2-3' } }
"rename phase 1 to 'Setup'"	{ type: 'update', target: 'phase', data: { id: 'phase-1', name: 'Setup' } }
"mark task-1-1 as completed"	{ type: 'update', target: 'task', data: { id: 'task-1-1', status: 'completed' } }
"add a new phase called Testing"	{ type: 'add', target: 'phase', data: { name: 'Testing' } }

If no update_request is provided, prompt the user:

What changes would you like to make to plan '{plan_name}'?

Examples:
  - "add a new task 'Write unit tests' to phase 2"
  - "remove the documentation phase"
  - "rename task-3-1 to 'API integration'"
  - "mark phase 1 as completed"

Enter your update request:

Step 4: Check Execution State

Determine if the plan is being executed:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js get-execution-state {plan_name}

If plan has started execution:

Show mode selection:

⚠️  Plan '{plan_name}' is currently being executed.

Progress: {completed}/{total} tasks ({percentage}%)
Completed phases: {completed_phases}
Current phase: {current_phase}

How would you like to proceed?

1. [selective] Apply changes to pending tasks only (recommended)
   - Completed work is preserved
   - Only pending tasks/phases can be modified
   - May need --force for some operations

2. [rollback] Reset and replan (full update)
   - All progress will be reset to pending
   - Execution history is preserved in logs
   - Start fresh with updated plan

3. [cancel] Cancel update

Choice [1/2/3]:

Step 5: Generate Preview

Show what changes will be made:

╔══════════════════════╗
║  Plan Update Preview ║
╚══════════════════════╝

Plan: {plan_name}
Mode: {selective|rollback}

─── Summary ────────────────────────────────────────────
  Operations: {count}
    + Additions: {add_count}
    ~ Updates: {update_count}
    - Deletions: {delete_count}

─── Operations ─────────────────────────────────────────
  + [1] ADD task: "Write unit tests"
        Phase: phase-2-implementation
        Description: Create comprehensive test suite

  ~ [2] UPDATE task: task-3-1
        description: "API endpoints" → "API integration"

  - [3] DELETE phase: phase-4-documentation
        ⚠ Contains 3 tasks that will also be deleted

─── Warnings ───────────────────────────────────────────
  ⚠  Deleting phase with completed tasks - use --force
  ⚠  Some operations affect completed work

─── Safety Notices ─────────────────────────────────────
  ⚠ DESTRUCTIVE: This update includes 1 deletion(s)

Step 6: Confirm with User

Apply these changes? [+1 ~1 -1]
  [y] Yes, apply changes
  [n] No, cancel
  [e] Edit operations
  [?] Show help

Choice:

If user chooses 'e' (edit):

--- Edit Mode ---
Operations:
  [1] ADD task: "Write unit tests"
  [2] UPDATE task: task-3-1
  [3] DELETE phase: phase-4-documentation

Commands:
  remove <n>  - Remove operation #n
  done        - Finish editing and confirm
  cancel      - Cancel all changes

Edit>

Step 7: Execute Update

Based on mode selection:

For selective mode:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js plan-update-selective {plan_name} --operations '{operations_json}'

For rollback mode:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js plan-update-rollback {plan_name} --operations '{operations_json}'

Step 8: Report Results

Success:

✅ Plan Updated Successfully

Plan: {plan_name}
Mode: {mode}

Changes Applied:
  + Added 1 task
  ~ Updated 1 task
  - Deleted 1 phase (3 tasks removed)

Updated Progress: {new_completed}/{new_total} tasks

Next Steps:
  /session:plan-status {plan_name} - View updated plan
  /session:plan-execute {plan_name} - Continue execution

Partial Success (selective mode):

⚠️ Plan Partially Updated

Applied: 2 operations
Skipped: 1 operation (affects completed work)

Skipped Operations:
  - DELETE phase: phase-1-setup (completed, requires --force)

To apply skipped operations, use:
  /session:plan-update {plan_name} --force

Failure:

❌ Update Failed

Error: {error_message}

Details:
  - Operation 3 failed: {reason}
  - Validation error: {details}

Recovery:
  - Backup created at: .claude/plans/{plan_name}/.backups/backup-{timestamp}
  - To restore: /session:plan-restore {plan_name} {backup_name}

---

Quick Update Examples

Add a Task

/session:plan-update my-plan add a new task "Implement caching" to phase-2

Remove a Task

/session:plan-update my-plan remove task-3-2

Rename a Phase

/session:plan-update my-plan rename phase-1 to "Infrastructure Setup"

Mark Task Complete

/session:plan-update my-plan mark task-2-1 as completed

Add a New Phase

/session:plan-update my-plan add a new phase called "Performance Testing" after phase-3

Force Update (completed items)

/session:plan-update my-plan remove task-1-1 --force

---

Command Options

Option	Description
--force	Allow modifications to completed items
--yes	Skip confirmation prompt
--dry-run	Preview changes without applying
--mode selective	Only update pending items (default for executing plans)
--mode rollback	Reset progress and apply all changes
--json	Output results as JSON

---

Error Handling

Plan Not Found

❌ Error: Plan 'unknown-plan' not found

Available plans:
  - my-feature (in-progress, 45%)
  - refactor-api (pending, 0%)

Use /session:plan-list for full details.

Invalid Operation

❌ Error: Could not parse update request

Input: "do something to the plan"

Could not determine:
  - Operation type (add, remove, update?)
  - Target (phase, task?)

Try being more specific:
  - "add a task called 'X' to phase Y"
  - "remove task-1-2"
  - "rename phase-1 to 'New Name'"

Blocked by Execution State

❌ Error: Cannot modify in-progress task

Task 'task-2-3' is currently in progress.
Wait for completion or use rollback mode.

Options:
  1. Wait for task to complete
  2. Use /session:plan-update {plan} --mode rollback

Validation Error

❌ Error: Invalid operation

Cannot add task with duplicate ID 'task-1-1'
A task with this ID already exists in phase-1.

Suggestion: Let the system generate a unique ID automatically.

---

Related Commands

• /session:plan-status {name} - View current plan status
• /session:plan-execute {name} - Execute plan tasks
• /session:plan-list - List all plans
• /session:plan-save {name} - Create new plan
• /session:plan-finalize {name} - Finalize conceptual plan