plan-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan Manager Skill

计划管理器Skill

Operator Context

操作方上下文

This skill operates as an operator for plan lifecycle management, configuring Claude's behavior for consistent, deterministic plan operations that prevent stale plan execution and context drift. It implements the CLI-First pattern -- all lifecycle operations go through

scripts/plan-manager.py

, never manual file edits.

本Skill作为计划生命周期管理的操作工具，配置Claude的行为以实现一致、确定性的计划操作，防止过期计划执行和上下文偏移。它采用CLI优先模式——所有生命周期操作都通过

scripts/plan-manager.py

执行，绝不允许手动编辑文件。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution
Over-Engineering Prevention: Only perform requested plan operations. No speculative plan creation, no "while I'm here" cleanup of other plans
Staleness Check Required: ALWAYS run
```
list --stale
```
before executing any plan tasks
Re-read Before Decisions: Re-read plan via
```
show
```
before any decision that affects task direction
Show Before Modify: ALWAYS run
```
show PLAN_NAME
```
before completing or abandoning a plan
Complete Output Display: Show full script output to user; never summarize as "plan updated"
CLI-Only Lifecycle: Use
```
check
```
,
```
complete
```
,
```
abandon
```
commands; never edit plan files directly for lifecycle changes
Error Logging to Plan: When errors occur during plan work, log them to the plan's "Errors Encountered" section

CLAUDE.md合规性：执行前阅读并遵循仓库中的CLAUDE.md文件
避免过度设计：仅执行请求的计划操作。不进行推测性计划创建，不顺便清理其他计划
必须执行过期检查：在执行任何计划任务前，始终运行
```
list --stale
```
决策前重新读取：在任何影响任务方向的决策前，通过
```
show
```
重新读取计划
修改前先查看：在完成或废弃计划前，始终运行
```
show PLAN_NAME
```
完整输出展示：向用户展示脚本的完整输出；绝不总结为“计划已更新”
仅通过CLI管理生命周期：使用
```
check
```
、
```
complete
```
、
```
abandon
```
命令；绝不直接编辑计划文件进行生命周期变更
错误记录到计划：当计划工作中出现错误时，将其记录到计划的“遇到的错误”部分

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Communication Style: Report facts without self-congratulation. Show command output rather than describing it
Warning Escalation: Surface all staleness warnings prominently to user before proceeding
Confirmation Required: Ask for explicit confirmation before lifecycle changes (complete/abandon)
Task Context Display: When checking off tasks, show which task was marked and remaining count
Audit Trail: Always provide
```
--reason
```
with abandonment operations
Re-validation After Changes: Run
```
show
```
after any
```
check
```
,
```
complete
```
, or
```
create
```
to confirm state

沟通风格：只报告事实，不自我夸赞。展示命令输出而非描述输出内容
警告升级：在继续操作前，向用户突出显示所有过期警告
需要确认：在进行生命周期变更（完成/废弃）前，请求用户明确确认
任务上下文展示：标记任务完成时，显示已标记的任务和剩余任务数量
审计跟踪：执行废弃操作时，始终提供
```
--reason
```
参数
变更后重新验证：在任何
```
check
```
、
```
complete
```
或
```
create
```
操作后，运行
```
show
```
以确认状态

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

Batch Operations: Process multiple plans in sequence (only if explicitly requested)
Auto-create Plans: Create plans only when user explicitly requests plan creation
Skip Confirmation: Skip confirmation dialogs only when user requests fast mode

批量操作：按顺序处理多个计划（仅当明确请求时）
自动创建计划：仅当用户明确请求时才创建计划
跳过确认：仅当用户请求快速模式时，跳过确认对话框

What This Skill CAN Do

本Skill可执行的操作

List all active plans with staleness warnings
Show plan details, remaining tasks, and status
Check off completed tasks within plans
Move plans to completed or abandoned states
Create new plans with proper structure
Audit plan directory for structural issues

列出所有活跃计划并显示过期警告
查看计划详情、剩余任务和状态
标记计划中的任务为完成
将计划移至已完成或已废弃状态
创建结构规范的新计划
审计计划目录的结构问题

What This Skill CANNOT Do

本Skill不可执行的操作

Execute plan tasks (only tracks completion status)
Modify plan content directly (only lifecycle operations via CLI)
Auto-complete stale plans without user approval
Delete plans permanently (only move to abandoned)
Skip the staleness check at session start

执行计划任务（仅跟踪完成状态）
直接修改计划内容（仅通过CLI进行生命周期操作）
未经用户批准自动完成过期计划
永久删除计划（仅移至已废弃状态）
会话启动时跳过过期检查

Instructions

操作说明

Phase 1: ASSESS

阶段1：评估

Goal: Establish current plan state before any operations.

Step 1: Check for stale plans

bash

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.

Step 2: List active plans

bash

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

Show complete output to user. Never summarize.

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

目标：在执行任何操作前，确定当前计划状态。

步骤1：检查过期计划

bash

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

立即向用户显示任何过期警告。如果存在过期计划，在进行其他操作前先处理它们。

步骤2：列出活跃计划

bash

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

向用户展示完整输出。绝不总结。

关卡：过期检查完成。用户已了解计划状态。仅当关卡通过后才可继续。

Phase 2: OPERATE

阶段2：执行

Goal: Execute the requested plan operation with full validation.

For showing a plan:

bash

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

For checking off a task:

bash

undefined

目标：通过完整验证执行请求的计划操作。

查看计划时：

bash

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

标记任务完成时：

bash

undefined

Re-read plan first (keeps goals in recency window)

先重新读取计划（确保目标在近期上下文窗口中）

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

Mark task complete

标记任务完成

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

Confirm updated state

确认更新后的状态

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


**For completing a plan:**

```bash

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


**完成计划时**：

```bash

Show full status first (MANDATORY)

先查看完整状态（必须执行）

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

Ask user: "Complete this plan? (y/n)"

询问用户：“是否完成此计划？(y/n)”

On confirmation:

确认后执行：

python3 ~/.claude/scripts/plan-manager.py complete PLAN_NAME


**For abandoning a plan:**

```bash

python3 ~/.claude/scripts/plan-manager.py complete PLAN_NAME


**废弃计划时**：

```bash

Show full status first (MANDATORY)

先查看完整状态（必须执行）

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

Ask user for reason

向用户询问原因

python3 ~/.claude/scripts/plan-manager.py abandon PLAN_NAME --reason "User requested: [reason]"


**For creating a plan:**

```bash

python3 ~/.claude/scripts/plan-manager.py abandon PLAN_NAME --reason "用户请求：[原因]"


**创建计划时**：

```bash

Confirm name (lowercase-kebab-case) and title with user first

先与用户确认名称（小写短横线格式）和标题

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. Output shown to user in full. State confirmed with follow-up `show`. Proceed only when gate passes.

python3 ~/.claude/scripts/plan-manager.py create PLAN_NAME --title "描述性标题" python3 ~/.claude/scripts/plan-manager.py show PLAN_NAME


**关卡**：通过CLI执行操作。向用户展示完整输出。通过后续的`show`确认状态。仅当关卡通过后才可继续。

Phase 3: VERIFY

阶段3：验证

Goal: Confirm operation succeeded and state is consistent.

Step 1: Run

show

on the affected plan to confirm changes took effect.

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

bash

ls plan/completed/   # or plan/abandoned/

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

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

目标：确认操作成功且状态一致。

步骤1：对受影响的计划运行

show

以确认变更已生效。

步骤2：如果是生命周期变更（完成/废弃），验证计划已移动：

bash

ls plan/completed/   # 或 plan/abandoned/

步骤3：向用户报告最终状态并展示完整输出。

关卡：计划状态已验证。用户已被告知。操作完成。

Command Reference

命令参考

User Intent	Command	Example
"what's on our plan"	`list`	`python3 ~/.claude/scripts/plan-manager.py list --human`
"check for stale plans"	`list --stale`	`python3 ~/.claude/scripts/plan-manager.py list --stale`
"show me plan X"	`show PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py show add-auth`
"what tasks remain"	`show --tasks`	`python3 ~/.claude/scripts/plan-manager.py show add-auth --tasks`
"mark task done"	`check PLAN_NAME N`	`python3 ~/.claude/scripts/plan-manager.py check add-auth 3`
"finish this plan"	`complete PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py complete add-auth`
"stop this plan"	`abandon PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py abandon add-auth --reason "..."`
"create a plan for X"	`create PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py create add-auth --title "..."`
"audit plans"	`audit`	`python3 ~/.claude/scripts/plan-manager.py audit`

用户意图	命令	示例
“我们的计划有哪些内容”	`list`	`python3 ~/.claude/scripts/plan-manager.py list --human`
“检查过期计划”	`list --stale`	`python3 ~/.claude/scripts/plan-manager.py list --stale`
“给我看计划X”	`show PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py show add-auth`
“还剩哪些任务”	`show --tasks`	`python3 ~/.claude/scripts/plan-manager.py show add-auth --tasks`
“标记任务完成”	`check PLAN_NAME N`	`python3 ~/.claude/scripts/plan-manager.py check add-auth 3`
“完成此计划”	`complete PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py complete add-auth`
“停止此计划”	`abandon PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py abandon add-auth --reason "..."`
“为X创建计划”	`create PLAN_NAME`	`python3 ~/.claude/scripts/plan-manager.py create add-auth --title "..."`
“审计计划”	`audit`	`python3 ~/.claude/scripts/plan-manager.py audit`

Exit Codes

退出码

Code	Meaning	Action
0	Success	Continue normally
1	Error	Stop and report error message to user
2	Warning	Continue but inform user of warnings

代码	含义	操作
0	成功	正常继续
1	错误	停止并向用户报告错误消息
2	警告	继续但向用户告知警告信息

Error Handling

错误处理

Error: "Plan not found"

错误：“未找到计划”

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

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

原因：计划名称拼写错误，或计划已移至已完成/已废弃目录解决方案：

运行
```
list
```
查看可用的活跃计划
检查
```
plan/completed/
```
和
```
plan/abandoned/
```
目录
确认拼写完全匹配（短横线格式）

Error: "Task number out of range"

错误：“任务编号超出范围”

Cause: Task number does not exist in the plan Solution:

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

原因：任务编号在计划中不存在解决方案：

运行
```
show PLAN_NAME --tasks
```
查看有效的任务编号
任务编号从1开始计数；确认正确的编号
重新读取计划以确认任务列表未变更

Error: "Cannot complete: unchecked tasks"

错误：“无法完成：存在未标记完成的任务”

Cause: Attempting to complete a plan with remaining tasks Solution:

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

原因：尝试完成仍有剩余任务的计划解决方案：

运行
```
show PLAN_NAME --tasks
```
查看剩余任务
要么先标记剩余任务为完成，要么询问用户是否要强制完成
如果强制完成，记录未标记任务可被接受的原因

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

原因：废弃命令缺少

--reason

参数解决方案：废弃时始终提供

--reason "..."

——这是审计跟踪的必填项

Anti-Patterns

反模式

Anti-Pattern 1: Executing Without Staleness Check

反模式1：未执行过期检查就开始操作

What it looks like: User says "let's work on the auth plan" and assistant immediately starts tasks Why wrong: Plan may be 30 days old with outdated requirements. Stale plans waste effort on obsolete work. Do instead: Run

list --stale

first. Surface warnings. Then proceed.

表现：用户说“我们来处理认证计划”，助手立即开始执行任务 错误原因：计划可能已过期30天，需求已过时。过期计划会导致在已废弃的工作上浪费精力。 正确做法：先运行

list --stale

。显示警告。然后再继续。

Anti-Pattern 2: Completing Without Showing

反模式2：未查看就完成计划

What it looks like: Running

complete auth-plan

without first running

show auth-plan

Why wrong: May complete plan with unchecked tasks, losing track of incomplete work. Do instead: Always

show

before

complete

abandon

. Review output. Then proceed.

表现：直接运行

complete auth-plan

而不先运行

show auth-plan

错误原因：可能会在存在未完成任务的情况下完成计划，导致丢失未完成工作的跟踪。 正确做法：在

complete

或

abandon

前始终执行

show

。查看输出。然后再继续。

Anti-Pattern 3: Summarizing Script Output

反模式3：总结脚本输出

What it looks like: "You have 3 active plans and 1 is stale" instead of showing full CLI output Why wrong: Hides which plan is stale, how stale, what tasks remain. User loses critical detail. Do instead: Show complete script output. Let the user read the details.

表现：说“你有3个活跃计划，其中1个已过期”，而非展示完整的CLI输出 错误原因：隐藏了哪个计划过期、过期多久、剩余哪些任务等信息。用户会丢失关键细节。 正确做法：展示完整的脚本输出。让用户自行阅读细节。

Anti-Pattern 4: Manual Plan File Editing

反模式4：手动编辑计划文件

What it looks like: Using Edit tool to modify

plan/active/auth-plan.md

directly for lifecycle changes Why wrong: Bypasses CLI validation. May corrupt plan format. Loses audit trail. Do instead: Use

check

complete

abandon

commands. Only edit directly when adding new tasks to plan content.

表现：使用编辑工具直接修改

plan/active/auth-plan.md

进行生命周期变更 错误原因：绕过了CLI验证。可能会破坏计划格式。丢失审计跟踪。 正确做法：使用

check

、

complete

、

abandon

命令。仅当向计划内容添加新任务时才可直接编辑。

Anti-Pattern 5: Creating Plans Without User Confirmation

反模式5：未经过用户确认就创建计划

What it looks like: User says "we should add authentication" and assistant immediately creates a plan Why wrong: User may want to discuss scope first. Creates clutter with unwanted plans. Do instead: Ask "Would you like me to create a plan for this? What should it be called and what tasks should it include?"

表现：用户说“我们应该添加认证功能”，助手立即创建计划 错误原因：用户可能想先讨论范围。会创建不必要的计划造成混乱。 正确做法：询问“是否需要我为此创建计划？计划名称是什么，应该包含哪些任务？”

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本Skill使用以下共享模式：

反合理化 - 防止寻找捷径的合理化行为
验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"Plan looks current enough"	Staleness dates matter, not appearance	Run `list --stale` first
"Tasks seem mostly done"	Check marks are source of truth	Run `show --tasks` first
"I'll mark it complete later"	Lifecycle drift causes stale plans	Complete or abandon promptly
"The script is slow, I'll check manually"	Manual checks miss edge cases	Always use the CLI
"Plan is obvious, no need to show first"	Context prevents mistakes	Always `show` before `complete` / `abandon`

合理化理由	错误原因	要求操作
“计划看起来是最新的”	过期日期很重要，外观不重要	先运行 `list --stale`
“任务似乎差不多完成了”	勾选标记是事实来源	先运行 `show --tasks`
“我稍后再标记完成”	生命周期偏移会导致计划过期	及时完成或废弃计划
“脚本太慢了，我手动检查”	手动检查会遗漏边缘情况	始终使用CLI
“计划内容很明确，不需要先查看”	上下文可防止错误	在 `complete` / `abandon` 前始终执行 `show`

Reference Files

参考文件

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

计划格式文档：
```
plan/README.md
```
CLI实现：
```
scripts/plan-manager.py
```