Plan Manager Skill

Overview

This skill manages the complete lifecycle of task plans using a deterministic CLI-first pattern: all operations flow through scripts/plan-manager.py, never through manual file edits. This prevents stale plan execution, context drift, and loss of audit trails. Use this skill when the user needs to list, create, show, track, complete, or abandon plans — not for executing the tasks within plans themselves.

Instructions

Phase 1: ASSESS Plan State

Goal: Establish current plan state and surface any stale plans before proceeding with operations.

Always start with staleness check (because stale plans waste effort on obsolete work):

python3 ~/.claude/scripts/plan-manager.py list --stale

Surface any staleness warnings to user immediately. If stale plans exist, address them before proceeding with other operations.

Then list active plans (because you need context before making decisions):

python3 ~/.claude/scripts/plan-manager.py list --human

Show complete output to user. Never summarize or abbreviate — the raw output contains critical details about plan age, task counts, and status that the user needs to see.

Gate: Staleness check complete. User informed of plan state. Proceed only when gate passes.

Phase 2: OPERATE - Execute the Requested Plan Action

Goal: Execute the requested plan operation with full context and validation.

For showing a plan:

python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME
python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME --tasks

For checking off a task:

Re-read the plan first before marking tasks (because this keeps the plan's goals in your recency window and prevents context drift):

python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME
python3 ~/.claude/scripts/plan-manager.py check PLAN_NAME TASK_NUMBER
python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME --tasks

Then show updated state to user, including which task was marked and remaining count.

For completing a plan:

Show full status first before completing (because you must verify all checked tasks and understand what you're completing):

python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME
# Ask user: "Complete this plan? (y/n)"
# On confirmation:
python3 ~/.claude/scripts/plan-manager.py complete PLAN_NAME

For abandoning a plan:

Show full status first (because context prevents premature abandonment), then request explicit reason (because the audit trail requires documented rationale):

python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME
# Ask user: "Why abandon this plan?"
python3 ~/.claude/scripts/plan-manager.py abandon PLAN_NAME --reason "User requested: [reason]"

For creating a plan:

Confirm the plan name (lowercase-kebab-case) and descriptive title with user first (because speculative plan creation creates clutter; only create when explicitly requested):

python3 ~/.claude/scripts/plan-manager.py create PLAN_NAME --title "Descriptive title"
python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME

Gate: Operation executed via CLI, never via manual file edit. Full output shown to user. State confirmed with follow-up show. Proceed only when gate passes.

Phase 3: VERIFY - Confirm Successful State Change

Goal: Confirm operation succeeded and state is consistent.

Step 1: Run show on the affected plan to confirm changes took effect (because CLI operations must be validated).

Step 2: If lifecycle change (complete/abandon), verify the plan moved to the correct directory:

ls plan/completed/   # or plan/abandoned/

Step 3: Report final state to user with full output.

When errors occur during plan work, log them to the plan's "Errors Encountered" section (because this maintains a record for future sessions and prevents knowledge loss).

Gate: Plan state verified. User informed. Operation complete.

Error: "Plan not found"

Cause: Plan name misspelled or plan already moved to completed/abandoned

Solution:

1. Run list to see available active plans
2. Check plan/completed/ and plan/abandoned/ directories
3. Verify spelling matches exactly (kebab-case)

Error: "Task number out of range"

Cause: Task number does not exist in the plan

Solution:

1. Run show PLAN_NAME --tasks to see valid task numbers
2. Task numbers are 1-indexed; verify the correct number
3. Re-read plan to confirm task list hasn't changed

Error: "Cannot complete: unchecked tasks"

Cause: Attempting to complete a plan with remaining tasks

Solution:

1. Run show PLAN_NAME --tasks to see remaining tasks
2. Either check remaining tasks first or ask user if they want to force-complete
3. Document why unchecked tasks are acceptable if force-completing

Error: "Reason required for abandonment"

Cause: Missing --reason flag on abandon command

Solution: Always provide --reason "..." when abandoning — this is mandatory for the audit trail

---

References

• Plan format documentation: plan/README.md
• CLI implementation: scripts/plan-manager.py