monoco-toolkit 0.3.6__py3-none-any.whl → 0.3.10__py3-none-any.whl

monoco/features/issue/resources/zh/skills/issue_lifecycle_workflow/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: issue-lifecycle-workflow
+description: Issue 生命周期工作流 (Flow Skill)。定义从创建到关闭的完整 Issue 管理流程，确保任务追踪和流程合规。
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Lifecycle Workflow
+
+Issue 生命周期的标准化工作流，确保 "Open → Start → Develop → Submit → Review → Close" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Open: 创建 Issue
+    
+    Open --> Start: 准备开发
+    Open --> Open: 需求不清<br/>(等待澄清)
+    
+    Start --> Develop: 分支创建
+    Start --> Start: 分支冲突<br/>(解决冲突)
+    
+    Develop --> Submit: 开发完成
+    Develop --> Develop: 测试失败<br/>(修复代码)
+    
+    state "Oracle Loop" as ReviewLoop {
+        Submit --> Review: 提交评审
+        Review --> Fix: 拒绝
+        Fix --> Submit: 重新提交
+    }
+    
+    Review --> Close: 批准合并
+    
+    Close --> [*]: 清理完成
+```
+
+## 执行步骤
+
+### 1. Open (创建)
+
+- **目标**: 创建清晰、可执行的 Issue
+- **输入**: 需求描述、类型、优先级
+- **输出**: Issue Ticket 文件
+- **检查点**:
+  - [ ] 使用 `monoco issue create <type> -t "标题"`
+  - [ ] 选择合适的类型（epic/feature/chore/fix）
+  - [ ] 编写清晰的描述和验收标准
+  - [ ] 设置依赖关系（如需要）
+  - [ ] 确保至少 2 个 Checkbox
+
+### 2. Start (启动)
+
+- **目标**: 准备开发环境，创建功能分支
+- **检查点**:
+  - [ ] 运行 `monoco issue start <ID> --branch`
+  - [ ] 确认分支已创建并切换
+  - [ ] 验证当前不在 main/master 分支
+  - [ ] 检查依赖 Issue 是否已完成
+
+### 3. Develop (开发)
+
+- **目标**: 实现功能或修复缺陷
+- **策略**: 迭代开发，持续测试
+- **检查点**:
+  - [ ] 遵循项目代码规范
+  - [ ] 编写/更新单元测试
+  - [ ] 运行测试套件，确保通过
+  - [ ] 定期提交代码（小步提交）
+  - [ ] 更新文件追踪（`monoco issue sync-files`）
+
+### 4. Submit (提交)
+
+- **目标**: 准备代码评审
+- **检查点**:
+  - [ ] 运行 `monoco issue lint` 检查合规性
+  - [ ] 修复所有 Lint 错误
+  - [ ] 更新任务清单状态
+  - [ ] 运行 `monoco issue submit <ID>`
+  - [ ] 编写变更摘要
+
+### 5. Review (评审)
+
+- **目标**: 代码质量和流程合规检查
+- **检查点**:
+  - [ ] 功能是否正确实现
+  - [ ] 代码是否符合设计规范
+  - [ ] 测试是否充分
+  - [ ] 文档是否同步更新
+  - [ ] 是否遵循项目规范
+
+### 6. Close (关闭)
+
+- **目标**: 完成 Issue，清理环境
+- **检查点**:
+  - [ ] 代码已合并到主分支
+  - [ ] 运行 `monoco issue close <ID> --solution completed --prune`
+  - [ ] 验证分支已清理
+  - [ ] 更新 Review Comments（如需要）
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 需求不清晰 | 返回 Open，请求澄清 |
+| 分支创建失败 | 检查 Git 状态，解决冲突 |
+| 测试失败 | 返回 Develop，修复代码 |
+| Lint 失败 | 修复合规性问题，重新 Submit |
+| 评审拒绝 | 返回 Develop，按反馈修改 |
+| 评审通过 | 进入 Close，合并并清理 |
+
+## 合规要求
+
+- **禁止**: 在 main/master 分支直接修改代码
+- **必须**: 使用 `monoco issue start --branch` 创建功能分支
+- **必须**: 所有单元测试通过后才能 Submit
+- **必须**: 每个 Issue 至少 2 个 Checkbox
+- **必须**: Review/Done 阶段必须包含 Review Comments
+- **建议**: 小步提交，频繁同步文件追踪
+
+## 相关命令
+
+```bash
+# 创建 Issue
+monoco issue create feature -t "标题"
+
+# 启动开发
+monoco issue start FEAT-0001 --branch
+
+# 同步文件追踪
+monoco issue sync-files
+
+# 检查合规性
+monoco issue lint
+
+# 提交评审
+monoco issue submit FEAT-0001
+
+# 关闭 Issue
+monoco issue close FEAT-0001 --solution completed --prune
+```
+
+## Issue 类型指南
+
+| 类型 | 用途 | 前缀 | Mindset |
+|------|------|------|---------|
+| Epic | 宏大目标、愿景容器 | EPIC- | Architect |
+| Feature | 用户价值增量 | FEAT- | Product Owner |
+| Chore | 工程性事务 | CHORE- | Builder |
+| Fix | 缺陷修复 | FIX- | Debugger |
+
+## 与 flow_engineer 的关系
+
+此工作流与 `flow_engineer` 互补：
+- `issue-lifecycle-workflow`: 关注 Issue 管理流程
+- `flow_engineer`: 关注代码实现流程
+
+Engineer 在执行 Develop 阶段时，应遵循 `flow_engineer` 的 Investigate → Code → Test → Report → Submit 流程。

monoco/features/issue/resources/zh/skills/issue_refine_workflow/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: issue-refine-workflow
+description: 调查并细化 Issue，补充技术细节和实现方案 (Copilot 模式)
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Refine Workflow
+
+对新创建或待细化的 Issue 进行技术调查、架构分析和方案设计的标准化工作流。
+
+**适用场景**: Copilot 模式（人类主导，AI 辅助）
+**目标用户**: 需要深入理解问题并制定实现方案的开发者
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Investigate: 开始细化
+    
+    Investigate --> Analyze: 收集信息
+    Investigate --> Investigate: 信息不足<br/>(继续调查)
+    
+    Analyze --> Architect: 需要架构设计
+    Analyze --> Document: 直接文档化
+    
+    Architect --> Document: 设计完成
+    
+    Document --> [*]: Issue 细化完成
+```
+
+## 执行步骤
+
+### 1. Investigate (调查)
+
+- **目标**: 全面收集与 Issue 相关的信息
+- **输入**: Issue Ticket、相关代码、文档
+- **输出**: 信息收集报告
+- **检查点**:
+  - [ ] 阅读 Issue 描述，理解核心问题
+  - [ ] 识别相关代码模块和文件
+  - [ ] 查看相关 Issue/PR 历史
+  - [ ] 检查外部依赖和约束条件
+  - [ ] 收集类似实现参考（Spike）
+
+**调查维度**:
+| 维度 | 调查内容 |
+|------|----------|
+| 代码 | 相关模块的当前实现 |
+| 历史 | 相关 Issue、PR、设计文档 |
+| 依赖 | 外部库、API、服务依赖 |
+| 约束 | 性能要求、安全要求、兼容性 |
+| 参考 | 类似功能的最佳实践 |
+
+### 2. Analyze (分析)
+
+- **目标**: 分析收集的信息，识别关键问题和方案选项
+- **检查点**:
+  - [ ] 分析架构继承性（如何融入现有架构）
+  - [ ] 评估安全性影响
+  - [ ] 评估性能影响
+  - [ ] 评估可维护性
+  - [ ] 识别潜在风险和缓解措施
+
+**分析框架**:
+
+#### 架构继承性
+- 现有架构模式是否适用？
+- 是否需要引入新的抽象层？
+- 对现有模块的耦合影响？
+
+#### 安全性评估
+- 输入验证需求
+- 权限控制需求
+- 数据保护需求
+- 潜在攻击面分析
+
+#### 性能评估
+- 时间复杂度影响
+- 空间复杂度影响
+- 并发/并行需求
+- 资源使用预估
+
+#### 可维护性评估
+- 代码复杂度变化
+- 测试覆盖需求
+- 文档更新需求
+- 后续扩展性
+
+### 3. Architect (架构) - 可选
+
+- **目标**: 对复杂 Issue 进行架构设计
+- **适用**: 涉及架构变更或大型功能
+- **检查点**:
+  - [ ] 确定技术方案选型
+  - [ ] 设计接口和交互协议
+  - [ ] 规划数据模型变更
+  - [ ] 制定实现里程碑
+
+**输出物**:
+- 架构决策记录 (ADR)
+- 接口设计文档
+- 数据模型变更
+- 里程碑计划
+
+### 4. Document (文档)
+
+- **目标**: 将分析结果更新到 Issue
+- **检查点**:
+  - [ ] 更新技术任务清单
+  - [ ] 添加架构决策说明
+  - [ ] 补充风险和缓解措施
+  - [ ] 更新验收标准（如需要）
+  - [ ] 添加参考链接和依赖说明
+  - [ ] 运行 `monoco issue lint` 验证合规性
+
+**细化后 Issue 结构**:
+
+```markdown
+## Objective
+[原有内容]
+
+## Acceptance Criteria
+- [ ] 验收标准 1
+- [ ] 验收标准 2
+
+## Technical Analysis
+
+### 现状分析
+描述当前代码状态和相关实现。
+
+### 方案选型
+| 方案 | 优点 | 缺点 | 决策 |
+|------|------|------|------|
+| A | ... | ... | 采纳/备选 |
+| B | ... | ... | 备选/放弃 |
+
+### 风险评估
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 风险1 | 高/中/低 | 措施... |
+
+## Technical Tasks
+- [ ] 任务 1
+- [ ] 任务 2
+
+## References
+- 相关 Issue: #XXX
+- 参考实现: [链接]
+- ADR: [链接]
+```
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 信息不足 | 返回 Investigate，继续收集 |
+| 需要架构设计 | 进入 Architect 阶段 |
+| 方案明确 | 直接进入 Document 阶段 |
+| 发现阻塞依赖 | 创建依赖 Issue，标记当前 Issue |
+| 问题过于复杂 | 建议拆分为多个 Issue |
+
+## 细化程度指南
+
+| Issue 类型 | 细化要求 |
+|------------|----------|
+| Epic | 必须包含架构设计、里程碑、子任务分解 |
+| Feature | 必须包含技术方案、风险评估、任务分解 |
+| Chore | 必须包含实施步骤、影响范围 |
+| Fix | 必须包含根因分析、修复方案、测试用例 |
+
+## 相关命令
+
+```bash
+# 查看 Issue 详情
+monoco issue show <ID>
+
+# 检查合规性
+monoco issue lint
+
+# 同步文件追踪
+monoco issue sync-files
+
+# 查看相关 Spike
+monoco spike list
+```
+
+## 与 flow_engineer 的关系
+
+此工作流与 `flow_engineer` 互补：
+- `issue-refine-workflow`: 关注 Issue 细化阶段，在开发前完成技术调查
+- `flow_engineer`: 关注代码实现阶段，执行 Investigate → Code → Test → Report → Submit
+
+细化阶段收集的信息将为 Engineer 阶段的 Investigate 提供重要输入。
+
+## Copilot 模式提示
+
+作为 AI Copilot，你应该：
+1. **主动探索**: 帮助开发者发现潜在问题和边界情况
+2. **提供对比**: 给出多个技术方案，分析优缺点
+3. **协助评估**: 帮助进行安全性、性能影响评估
+4. **提醒遗漏**: 检查是否有遗漏的关键信息或风险点

monoco/features/issue/resources/zh/{SKILL.md → skills/monoco_issue/SKILL.md}

@@ -1,6 +1,8 @@
 ---
 name: monoco-issue
 description: Monoco Issue System 的官方技能定义。将 Issue 视为通用原子 (Universal Atom)，管理 Epic/Feature/Chore/Fix 的生命周期。
+type: standard
+version: 1.0.0
 ---
 
 # 自我管理 (Monoco Issue System)
@@ -67,6 +69,50 @@ Monoco 强制采用 **Feature Branch** 模式。
 - **禁止主干开发**: **严禁** 直接在 `main`, `master`, `production` 分支上修改代码。Linter 会拦截此类行为。
 - **Submit**: 在提交 PR 前，运行 `monoco issue submit <ID>` 进行清理和预发布检查。
 
+## 标准化工作流 (Standardized Workflow)
+
+本指南引导 Agent 遵循 Monoco 标准 Issue 工作流。
+
+### 工作流图示
+
+```mermaid
+stateDiagram-v2
+    [*] --> Plan
+    Plan --> Build: monoco issue start
+    Build --> Submit: monoco issue submit
+    state "Oracle Loop" as Oracle {
+        Submit --> Review: Auto/Manual Review
+        Review --> Fix: Reject
+        Fix --> Submit: Retry
+    }
+    Review --> Merge: Approve
+    Merge --> [*]: monoco issue close
+```
+
+### 执行步骤
+
+1.  **Plan (计划阶段)**:
+    - 确保 Issue 已创作且处于 `Open` 状态。
+    - 验证需求描述与任务清单 (Acceptance Criteria)。
+
+2.  **Build (构建阶段)**:
+    - 运行 `monoco issue start <ID> --branch` (强制分支隔离)。
+    - 实现功能或修复缺陷。
+    - 运行 `monoco issue sync-files` 更新修改文件追踪。
+
+3.  **Submit (提交阶段 - Oracle 循环)**:
+    - 运行测试确保质量。
+    - 运行 `monoco issue lint` 检查合规性。
+    - 运行 `monoco issue submit <ID>` 触发评审。
+    - **如果** 收到报错或反馈：
+      - 修复问题。
+      - 重新运行测试。
+      - 重新运行提交。
+
+4.  **Merge (合并/关闭阶段)**:
+    - 一旦获得批准 (人工或自动)：
+    - 运行 `monoco issue close <ID> --solution completed --prune` 清理环境并下线。
+
 ### 2. 文件追踪 (File Tracking)
 
 为了保证上下文的自包含性 (Self-Contained Context)，Agent 必须记录修改过的文件。
@@ -136,3 +182,9 @@ Monoco 强制采用 **Feature Branch** 模式。
 Linter 包含环境感知防护：
 
 - 🛑 **Dirty Main Protection**: 当检测到处于受保护分支 (`main`/`master`) 且存在未提交变更时，Lint 将失败并阻止操作。
+
+### 6. ID 格式与层级 (ID Format & Hierarchy)
+
+- **ID 规范**: Issue ID 必须严格遵循 `TYPE-XXXX` 格式，其中 `XXXX` 必须是 4 位数字（示例: `FEAT-0001`, `FIX-9999`）。
+- **禁止后缀**: 禁止使用类似 `FEAT-0001-1` 这样带后缀的 ID。
+- **层级表达**: 子功能或子任务应通过 `parent` 字段（在 Front Matter 中）来关联父级 Issue，严禁通过 ID 命名约定（如加分级后缀）来表达层级关系。