zco-claude 0.0.8__py3-none-any.whl

ClaudeSettings/skills/zco-plan/SKILL.md

@@ -0,0 +1,661 @@
+---
+name: zco-plan
+description: 读取并执行 docs/plans/ 目录下的项目开发计划。当用户需要执行某个编号的计划任务时使用此 Skill。
+allowed-tools: Bash, Read, Glob
+---
+
+# 执行项目开发计划
+
+## 🎯 Skill 用途
+
+自动读取 `docs/plans/` 目录下的结构化计划文档，理解任务需求，并以 **plan 模式**设计实施方案。
+
+**核心功能**：
+- **查找计划文档**：根据序号在 `docs/plans/` 目录中定位计划文件
+- **读取计划内容**：解析 YAML front matter 和 Markdown 内容
+- **执行任务**：以 plan 模式理解需求并设计实施方案
+- **智能匹配**：支持多版本计划自动选择最新版本
+
+## 📋 何时使用此 Skill
+
+当以下情况发生时，Claude 会自动提议使用此 Skill（或您也可以手动请求）：
+
+1. **用户明确请求执行计划**
+   - "执行计划 002"
+   - "运行 plan 003"
+   - "/zco-plan 001"
+
+2. **用户提及计划文档**
+   - "按照 docs/plans/plan.002.*.md 实施"
+   - "实现计划 003 中的功能"
+
+3. **定期任务执行**
+   - 每日/每周的开发任务
+   - 迭代计划执行
+
+## 📥 参数说明
+
+**命令格式**：
+```bash
+zco-plan {seq_number}
+```
+
+**参数**：
+- `seq_number` - 计划序号（必需），任意位数字（1、02、003、0100 均可）
+
+**示例**：
+```bash
+zco-plan 002  # 执行计划 002
+zco-plan 010  # 执行计划 010
+```
+
+**无参数调用**：
+```bash
+zco-plan      # 列出所有可用计划
+```
+
+## 🚀 使用步骤
+
+### Step 1: 解析参数
+
+首先，我会提取用户提供的计划序号：
+
+```markdown
+用户输入：zco-plan 002
+提取序号：002
+```
+
+### Step 2: 查找计划文档
+
+使用 Glob 工具在 `docs/plans/` 目录查找匹配的计划文档：
+
+```bash
+# 查找模式：plan.{seq}.{extra}.md
+# 示例：plan.002.20260108.md, plan.2.feature.md, plan.0100.issue946.md
+```
+
+**查找逻辑**：
+1. ✅ 搜索 `docs/plans/plan.{seq}.*.md`（支持任意长度序号）
+2. ✅ 如果找到唯一文件 → 直接使用
+3. ✅ 如果找到多个文件 → 选择日期最新的（按文件名排序）
+4. ✅ 如果未找到 → 提示错误并列出可用计划
+
+### Step 3: 读取计划内容
+
+使用 Read 工具读取计划文档的完整内容：
+
+```bash
+# 读取计划文档
+cat docs/plans/plan.002.20260108.md
+```
+
+**文档结构**：
+```yaml
+---
+seq: 002
+title: "任务标题"
+author: ""
+status: "draft:0"
+priority: "p2:中:可纳入后续迭代计划"
+created_at: ""
+updated_at: ""
+tags: []
+---
+
+# 开发任务：{任务标题}
+
+## 🎯 目标
+任务核心目标
+
+## 📋 详细需求
+具体功能描述
+
+## ✅ 验证标准
+完成标准清单
+
+## 🧪 测试计划
+测试场景和用例
+```
+
+### Step 3.5: 自动更新计划状态
+
+**在开始执行任务前**，自动更新计划元数据：
+
+```bash
+# 调用 metadata 更新脚本
+echo '{"plan_path": "docs/plans/plan.002.md", "action": "start", "tags": ["feature", "backend"]}' | \
+  python3 .claude/zco-scripts/update-plan-metadata.py
+```
+
+**自动更新的字段**：
+- ✅ `status`: `draft:0` → `ongoing:2` (开始执行)
+- ✅ `created_at`: 首次执行时设置 (YYYY-MM-DD HH:MM:SS)
+- ✅ `updated_at`: 每次执行时更新
+- ✅ `tags`: Claude 根据任务内容生成
+
+**状态转换**：
+- `draft:0` → `ongoing:2` (开始执行)
+- `ongoing:2` → `completed:3` (任务完成)
+- `ongoing:2` → `failed:4` (执行失败)
+
+**执行完成后**：
+```bash
+# 成功完成
+echo '{"plan_path": "docs/plans/plan.002.md", "action": "complete"}' | \
+  python3 .claude/zco-scripts/update-plan-metadata.py
+
+# 执行失败
+echo '{"plan_path": "docs/plans/plan.002.md", "action": "fail"}' | \
+  python3 .claude/zco-scripts/update-plan-metadata.py
+```
+
+### Step 4: 解析并执行任务
+
+我会：
+1. ✅ 解析 YAML front matter 中的元数据
+2. ✅ 理解任务目标和详细需求
+3. ✅ 识别验证标准和测试计划
+4. ✅ **进入 plan 模式**设计实施方案
+5. ✅ 按照计划逐步执行任务
+
+### Step 5: 更新计划状态（自动）
+
+任务完成后，自动更新计划文档的状态字段：
+
+```yaml
+status: draft:0 → ongoing:2 → completed:3
+created_at: 2026-01-09 15:30:00 (首次执行时设置)
+updated_at: 2026-01-09 16:45:00 (每次执行时更新)
+```
+
+## 📝 计划文档格式说明
+
+### YAML Front Matter（元数据）
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| `seq` | 计划序号（任意位数字） | `002`, `1`, `0100` |
+| `title` | 任务标题 | `"实现用户认证功能"` |
+| `author` | 作者/负责人（可空） | `"张三"` 或 `""` |
+| `status` | 任务状态（枚举） | `draft:0`, `ongoing:2`, `completed:3` |
+| `priority` | 优先级（枚举） | `p0:紧急:重要`, `p2:中:可纳入后续迭代计划` |
+| `created_at` | 创建时间（自动填充） | `2026-01-09 15:30:00` |
+| `updated_at` | 更新时间（自动更新） | `2026-01-09 16:45:00` |
+| `tags` | 标签列表（自动生成） | `[feature, backend, api]` |
+
+**状态枚举值**：
+- `draft:0` - 起稿中
+- `ready:1` - 准备就绪
+- `ongoing:2` - 进行中（zco-plan 执行时自动设置）
+- `completed:3` - 执行完成（zco-plan 完成时自动设置）
+- `failed:4` - 执行失败
+- `canceled:5` - 已取消
+- `archived:8` - 已归档
+
+**优先级枚举值**：
+- `p0:紧急:重要` - 紧急且重要
+- `p1:高:当前迭代/排期内重点解决`
+- `p2:中:可纳入后续迭代计划`（默认）
+- `p3:低:可记录，待后续评估`
+- `p4:无:不影响当前迭代/排期`
+
+### Markdown 内容结构
+
+**必需部分**：
+- 🎯 **目标** - 任务核心目标（1-2 句话）
+- 📋 **详细需求** - 功能描述、特殊要求、输入输出
+- ✅ **验证标准** - 完成标准清单
+
+**推荐部分**：
+- 🧪 **测试计划** - 单元测试、集成测试、手动测试
+- 📚 **参考信息** - 相关文档、现有实现、技术选型
+
+## 🔧 查找计划文档逻辑
+
+### 单一匹配（最常见）
+
+```bash
+# 示例：只有一个 plan.002 的文件
+docs/plans/plan.002.20260108.md
+
+# 结果：直接使用此文件
+```
+
+### 多版本匹配
+
+```bash
+# 示例：存在多个 plan.002 的版本
+docs/plans/plan.002.20260105.md  # 旧版本
+docs/plans/plan.002.20260108.md  # 新版本
+
+# 结果：自动选择日期最新的（20260108）
+```
+
+**选择策略**：
+1. 按文件名字母序降序排序（`sort -r`）
+2. 选择第一个（日期最新的）
+
+### 未找到计划
+
+```bash
+# 用户输入：zco-plan 999
+# 结果：未找到任何 plan.999.*.md
+
+# 提示信息：
+未找到计划 999
+可用的计划列表：
+- plan.001.260107.md - 配置同步功能
+- plan.002.260108.md - .claudeignore 生成
+```
+
+## ⚠️ 注意事项
+
+### 前置条件
+
+- ✅ `docs/plans/` 目录必须存在
+- ✅ 计划文档命名格式必须为 `plan.{seq}.**.md`
+- ✅ 计划文档必须包含有效的 YAML front matter
+- ✅ seq_number 是数字（可以用0前缀, 比如001-999, 不限位数）
+
+### 计划文档规范
+
+- ✅ 使用标准模板创建（`docs/plans/plan.template.md`）
+- ✅ YAML front matter 格式正确
+- ✅ 至少包含目标、详细需求、验证标准三个部分
+- ✅ 验证标准使用清单格式（`- [ ]`）
+
+### 命名规范
+
+**正确格式**：
+```
+plan.001.20260108.md  ✅ (seq=001)
+plan.002.权限验证.md  ✅ (seq=002)
+plan.0100.issue946.md  ✅  (seq=0100)
+plan.0100.issue946.用户鉴权.md  ✅ (seq=0100)
+plan.1.20260108.md     ✅ (seq=1)
+plan.002.md            ✅ (seq=002)
+```
+
+**错误格式**：
+```
+plan-002-20260108.md   ❌ (使用了 - 而非 .)
+task.002.20260108.md   ❌ (不是 plan 前缀)
+```
+
+## 🐛 失败排查
+
+### 错误 1: "未找到计划 {seq}"
+
+**原因**：`docs/plans/` 目录中不存在对应序号的计划文档
+
+**解决方案**：
+```bash
+# 1. 查看所有可用计划
+ls docs/plans/
+
+# 2. 确认序号是否正确
+# 3. 或创建新的计划文档
+```
+
+### 错误 2: "docs/plans/ 目录不存在"
+
+**原因**：项目根目录缺少 `docs/plans/` 目录
+
+**解决方案**：
+```bash
+# 创建目录
+mkdir -p docs/plans/
+
+# 复制模板
+cp docs/plans/plan.template.md docs/plans/plan.001.$(date +%y%m%d).md
+```
+
+### 错误 3: YAML front matter 解析失败
+
+**原因**：计划文档的 YAML 格式不正确
+
+**解决方案**：
+```bash
+# 检查 YAML 语法
+head -15 docs/plans/plan.002.20260108.md
+
+# 确保格式为：
+# ---
+# key: value
+# ---
+```
+
+### 错误 4: 参数格式错误
+
+**原因**：seq_number 不是 3 位数字
+
+**解决方案**：
+```bash
+# 错误示例
+zco-plan 2     # 应该是 002
+zco-plan abc   # 必须是数字
+
+# 正确示例
+zco-plan 002   # ✅
+zco-plan 010   # ✅
+```
+
+## 📚 使用示例
+
+### 示例 1: 执行现有计划
+
+**用户请求**：
+```
+zco-plan 002
+```
+
+**Claude 执行流程**：
+1. ✅ 解析参数：seq = 002
+2. ✅ 查找文档：找到 `docs/plans/plan.002.20260108.md`
+3. ✅ 读取内容：解析 YAML 和 Markdown
+4. ✅ 显示计划概览：
+   ```
+   📋 计划 002：.claudeignore 生成功能
+   作者：张三
+   状态：pending
+   优先级：medium
+   创建时间：2026-01-08 10:30:00
+   ```
+5. ✅ 进入 plan 模式并执行任务
+
+### 示例 2: 列出所有可用计划
+
+**用户请求**：
+```
+zco-plan
+```
+
+**Claude 执行流程**：
+1. ✅ 扫描 `docs/plans/` 目录
+2. ✅ 列出所有计划文档：
+   ```
+   可用的计划列表：
+
+   📋 plan.001.260107.md
+      标题：配置同步功能
+      状态：completed
+      日期：2026-01-07
+
+   📋 plan.002.260108.md
+      标题：.claudeignore 生成
+      状态：pending
+      日期：2026-01-08
+   ```
+3. ✅ 提示用户选择要执行的计划
+
+### 示例 3: 处理多版本计划
+
+**用户请求**：
+```
+zco-plan 002
+```
+
+**文件系统状态**：
+```
+docs/plans/plan.002.20260105.md  (旧版本)
+docs/plans/plan.002.20260108.md  (新版本)
+```
+
+**Claude 执行流程**：
+1. ✅ 查找到 2 个匹配文件
+2. ✅ 按日期排序选择最新版本：`plan.002.20260108.md`
+3. ✅ 提示用户：
+   ```
+   找到多个版本的计划 002，自动选择最新版本：
+   ✅ plan.002.20260108.md (2026-01-08)
+   ```
+4. ✅ 继续执行
+
+### 示例 4: 计划不存在
+
+**用户请求**：
+```
+zco-plan 999
+```
+
+**Claude 执行流程**：
+1. ❌ 未找到任何匹配文件
+2. ✅ 提示错误并列出可用计划：
+   ```
+   未找到计划 999
+
+   可用的计划列表：
+   - plan.001.260107.md
+   - plan.002.260108.md
+
+   提示：
+   - 检查序号是否正确
+   - 或创建新的计划文档
+   ```
+
+## 🔗 相关资源
+
+### 项目文件
+
+- **计划目录**: `docs/plans/`
+- **计划模板**: `docs/plans/plan.template.md`
+- **使用指南**: `docs/plans/README.md`
+- **Skill 定义**: `.claude/skills/zco-plan/SKILL.md`（本文件）
+
+### 相关 Skills
+
+**命名约定**：所有自定义 skills 使用 `zco-` 前缀（Zhicheng Custom Operations）
+
+- `zco-docs-update` - 更新 CLAUDE.md 元信息
+- `zco-plan` - 执行项目开发计划（本 Skill）
+
+### 创建新计划
+
+**方式 1：手动创建**
+```bash
+# 1. 复制模板
+cp docs/plans/plan.template.md docs/plans/plan.003.$(date +%y%m%d).md
+
+# 2. 编辑文档
+vim docs/plans/plan.003.260108.md
+
+# 3. 填写任务信息
+```
+
+**方式 2：使用脚本（如果可用）**
+```bash
+# 自动创建新计划
+bash .claude/zco-scripts/co-plan-new.sh 003 "实现用户认证"
+```
+
+## 💡 最佳实践
+
+### 1. 计划文档管理
+
+**命名约定**：
+- ✅ 使用 3 位序号：001, 002, 003...
+- ✅ 使用 YYMMDD 日期格式：260108
+- ✅ 保持简洁：`plan.{seq}.{date}.md`
+
+**版本控制**：
+- ✅ 提交计划文档到 Git
+- ✅ 重大修改时创建新版本（新日期）
+- ✅ 完成后更新 status 字段
+
+**目录组织**：
+```
+docs/plans/
+├── plan.001.260107.md  (已完成)
+├── plan.002.260108.md  (进行中)
+├── plan.003.260108.md  (待开始)
+├── plan.template.md    (模板)
+└── README.md           (使用指南)
+```
+
+### 2. 任务执行流程
+
+**推荐工作流**：
+1. 创建计划文档（填写需求和验证标准）
+2. 提交到 Git（团队审查）
+3. 执行计划：`zco-plan {seq}`
+4. Claude 设计方案（plan 模式）
+5. 用户审批方案
+6. Claude 实施任务
+7. 验证完成标准
+8. 更新计划状态为 `completed`
+
+### 3. 计划文档质量
+
+**必须包含**：
+- ✅ 清晰的目标描述
+- ✅ 详细的功能需求
+- ✅ 明确的验证标准
+- ✅ 输入输出规范
+
+**推荐包含**：
+- ⭐ 测试计划
+- ⭐ 参考资料
+- ⭐ 技术选型依据
+- ⭐ 潜在风险说明
+
+### 4. 与团队协作
+
+**共享计划**：
+- ✅ 计划文档提交到 Git
+- ✅ Code Review 时审查计划内容
+- ✅ 使用统一的模板格式
+- ✅ 定期清理已完成的计划
+
+**状态同步**：
+- `pending` - 待开始
+- `in-progress` - 进行中
+- `completed` - 已完成
+- `cancelled` - 已取消
+
+## 🎓 技术细节
+
+### Skill 调用逻辑
+
+1. **参数提取**：
+   ```
+   用户输入 "zco-plan 002"
+   → 提取参数 args = "002"
+   → 验证格式（3 位数字）
+   ```
+
+2. **文档查找**：
+   ```
+   → 使用 Glob: docs/plans/plan.002.*.md
+   → 排序选择最新版本
+   → 验证文件存在性
+   ```
+
+3. **内容读取**：
+   ```
+   → 使用 Read 读取完整文档
+   → Claude 自然理解 YAML + Markdown
+   → 无需手动解析 YAML
+   ```
+
+4. **任务执行**：
+   ```
+   → 进入 plan 模式
+   → 设计实施方案
+   → 等待用户批准
+   → 执行任务
+   ```
+
+### 工具限制
+
+**允许的工具**：
+- ✅ `Bash` - 执行 find、ls 等命令
+- ✅ `Read` - 读取计划文档
+- ✅ `Glob` - 搜索匹配文件
+
+**禁止的工具**（仅读取，不修改）：
+- ❌ `Write` - 不能创建文件
+- ❌ `Edit` - 不能修改文档
+
+**原因**：Skill 只负责读取和执行计划，创建和修改由用户或专用脚本完成。
+
+### 错误处理策略
+
+```python
+# 伪代码示例
+def execute_plan(seq_number):
+    # 1. 验证参数
+    if not is_valid_seq(seq_number):
+        return error("序号必须是 3 位数字")
+
+    # 2. 查找文档
+    files = glob(f"docs/plans/plan.{seq_number}.*.md")
+
+    if len(files) == 0:
+        list_all_plans()  # 显示可用计划
+        return error(f"未找到计划 {seq_number}")
+
+    if len(files) > 1:
+        plan_file = max(files)  # 选择最新
+        warn(f"找到多个版本，使用最新: {plan_file}")
+    else:
+        plan_file = files[0]
+
+    # 3. 读取并执行
+    content = read_file(plan_file)
+    show_plan_summary(content)
+    execute_in_plan_mode(content)
+```
+
+## 🌟 扩展功能（未来）
+
+### 计划状态自动更新
+
+```yaml
+# 执行前
+status: pending
+
+# 执行时
+status: in-progress
+updated: 2026-01-08 14:30:00
+
+# 完成后
+status: completed
+updated: 2026-01-08 16:45:00
+```
+
+### 计划列表命令
+
+```bash
+# 显示所有计划
+zco-plan-list
+
+# 按状态过滤
+zco-plan-list --status=pending
+
+# 按优先级过滤
+zco-plan-list --priority=high
+```
+
+### 计划归档
+
+```bash
+# 自动归档已完成计划
+docs/plans/plan.001.260107.md
+→ docs/plans/archive/2026/01/plan.001.260107.md
+```
+
+### 计划模板库
+
+```
+docs/plans/templates/
+├── feature.md     # 新功能开发模板
+├── bugfix.md      # Bug 修复模板
+├── refactor.md    # 重构任务模板
+└── research.md    # 技术研究模板
+```
+
+---
+
+**Skill 版本**: 1.0.0
+**最后更新**: 2026-01-08
+**维护者**: 开发团队