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

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

@@ -0,0 +1,203 @@
+---
+name: issue-refine-workflow
+description: Investigate and refine Issue, supplement technical details and implementation plan (Copilot Mode)
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Refine Workflow
+
+Standardized workflow for technical investigation, architecture analysis and solution design for newly created or pending refinement Issues.
+
+**Applicable Scenario**: Copilot Mode (Human-led, AI-assisted)
+**Target Users**: Developers who need to deeply understand problems and formulate implementation plans
+
+## Workflow State Machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> Investigate: Start Refinement
+    
+    Investigate --> Analyze: Gather Information
+    Investigate --> Investigate: Insufficient Information<br/>(Continue Investigation)
+    
+    Analyze --> Architect: Architecture Design Required
+    Analyze --> Document: Direct Documentation
+    
+    Architect --> Document: Design Complete
+    
+    Document --> [*]: Issue Refinement Complete
+```
+
+## Execution Steps
+
+### 1. Investigate
+
+- **Goal**: Comprehensively gather information related to the Issue
+- **Input**: Issue Ticket, related code, documentation
+- **Output**: Information gathering report
+- **Checkpoints**:
+  - [ ] Read Issue description, understand core problem
+  - [ ] Identify related code modules and files
+  - [ ] Review related Issue/PR history
+  - [ ] Check external dependencies and constraints
+  - [ ] Collect similar implementation references (Spike)
+
+**Investigation Dimensions**:
+| Dimension | Investigation Content |
+|-----------|----------------------|
+| Code | Current implementation of related modules |
+| History | Related Issues, PRs, design documents |
+| Dependencies | External libraries, APIs, service dependencies |
+| Constraints | Performance requirements, security requirements, compatibility |
+| References | Best practices for similar features |
+
+### 2. Analyze
+
+- **Goal**: Analyze gathered information, identify key problems and solution options
+- **Checkpoints**:
+  - [ ] Analyze architecture inheritance (how to fit into existing architecture)
+  - [ ] Assess security impact
+  - [ ] Assess performance impact
+  - [ ] Assess maintainability
+  - [ ] Identify potential risks and mitigation measures
+
+**Analysis Framework**:
+
+#### Architecture Inheritance
+- Are existing architecture patterns applicable?
+- Is a new abstraction layer needed?
+- Impact on coupling with existing modules?
+
+#### Security Assessment
+- Input validation requirements
+- Access control requirements
+- Data protection requirements
+- Potential attack surface analysis
+
+#### Performance Assessment
+- Time complexity impact
+- Space complexity impact
+- Concurrency/parallelism requirements
+- Resource usage estimation
+
+#### Maintainability Assessment
+- Code complexity changes
+- Test coverage requirements
+- Documentation update requirements
+- Future extensibility
+
+### 3. Architect (Optional)
+
+- **Goal**: Architecture design for complex Issues
+- **Applicable**: Issues involving architecture changes or large features
+- **Checkpoints**:
+  - [ ] Determine technical solution selection
+  - [ ] Design interfaces and interaction protocols
+  - [ ] Plan data model changes
+  - [ ] Define implementation milestones
+
+**Outputs**:
+- Architecture Decision Record (ADR)
+- Interface design document
+- Data model changes
+- Milestone plan
+
+### 4. Document
+
+- **Goal**: Update analysis results to Issue
+- **Checkpoints**:
+  - [ ] Update technical task list
+  - [ ] Add architecture decision explanation
+  - [ ] Supplement risks and mitigation measures
+  - [ ] Update acceptance criteria (if needed)
+  - [ ] Add reference links and dependency descriptions
+  - [ ] Run `monoco issue lint` to verify compliance
+
+**Refined Issue Structure**:
+
+```markdown
+## Objective
+[Original Content]
+
+## Acceptance Criteria
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+## Technical Analysis
+
+### Current State Analysis
+Describe current code state and related implementation.
+
+### Solution Selection
+| Solution | Pros | Cons | Decision |
+|----------|------|------|----------|
+| A | ... | ... | Adopted/Alternative |
+| B | ... | ... | Alternative/Abandoned |
+
+### Risk Assessment
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Risk1 | High/Medium/Low | Measure... |
+
+## Technical Tasks
+- [ ] Task 1
+- [ ] Task 2
+
+## References
+- Related Issue: #XXX
+- Reference Implementation: [Link]
+- ADR: [Link]
+```
+
+## Decision Branches
+
+| Condition | Action |
+|-----------|--------|
+| Insufficient information | Return to Investigate, continue gathering |
+| Architecture design needed | Enter Architect phase |
+| Solution is clear | Directly enter Document phase |
+| Blocking dependency found | Create dependency Issue, mark current Issue |
+| Problem too complex | Suggest splitting into multiple Issues |
+
+## Refinement Level Guide
+
+| Issue Type | Refinement Requirements |
+|------------|------------------------|
+| Epic | Must include architecture design, milestones, subtask decomposition |
+| Feature | Must include technical solution, risk assessment, task decomposition |
+| Chore | Must include implementation steps, impact scope |
+| Fix | Must include root cause analysis, fix solution, test cases |
+
+## Related Commands
+
+```bash
+# View Issue details
+monoco issue show <ID>
+
+# Check compliance
+monoco issue lint
+
+# Sync file tracking
+monoco issue sync-files
+
+# View related Spike
+monoco spike list
+```
+
+## Relationship with flow_engineer
+
+This workflow complements `flow_engineer`:
+- `issue-refine-workflow`: Focuses on Issue refinement phase, completing technical investigation before development
+- `flow_engineer`: Focuses on code implementation phase, executing Investigate → Code → Test → Report → Submit
+
+Information gathered during refinement phase will provide important input for the Engineer phase's Investigate.
+
+## Copilot Mode Tips
+
+As an AI Copilot, you should:
+1. **Explore proactively**: Help developers discover potential issues and edge cases
+2. **Provide comparisons**: Give multiple technical solutions, analyze pros and cons
+3. **Assist evaluation**: Help with security, performance impact assessment
+4. **Remind omissions**: Check for missing key information or risk points

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

@@ -1,6 +1,8 @@
 ---
 name: monoco-issue
 description: Official skill for Monoco Issue System. Treats Issues as Universal Atoms, managing the lifecycle of Epic/Feature/Chore/Fix.
+type: standard
+version: 1.0.0
 ---
 
 # Issue Management

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

@@ -0,0 +1,167 @@
+---
+name: issue-create-workflow
+description: 从 Memo 提取改进线索，分类并创建 Issue Ticket (Copilot 模式)
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Create Workflow
+
+从 Memo 中提取改进线索，分析并创建结构化 Issue Ticket 的标准化工作流。
+
+**适用场景**: Copilot 模式（人类主导，AI 辅助）
+**目标用户**: 需要快速将想法/笔记转化为可执行任务的开发者
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Extract: 读取 Memo
+    
+    Extract --> Classify: 识别类型
+    Extract --> Archive: 无价值
+    
+    Classify --> Design: 需要架构设计
+    Classify --> Direct: 直接创建
+    
+    Design --> Create: 设计完成
+    Direct --> Create: 直接创建
+    
+    Archive --> [*]: 归档 Memo
+    Create --> [*]: Issue 创建完成
+```
+
+## 执行步骤
+
+### 1. Extract (提取)
+
+- **目标**: 从 Memo 中提取关键改进线索
+- **输入**: Memo 文件或临时笔记
+- **输出**: 结构化的改进线索列表
+- **检查点**:
+  - [ ] 运行 `monoco memo list` 查看待处理 Memo
+  - [ ] 分析每个 Memo 的改进类型和影响范围
+  - [ ] 识别可执行的改进点（非纯参考资料）
+  - [ ] 记录改进的动机和预期效果
+
+**分析维度**:
+| 维度 | 问题 |
+|------|------|
+| 价值 | 这个改进解决什么问题？ |
+| 范围 | 影响哪些模块/功能？ |
+| 紧急 | 是现在做还是以后做？ |
+| 可行 | 是否有足够信息开始？ |
+
+### 2. Classify (分类)
+
+- **目标**: 确定 Issue 类型和优先级
+- **检查点**:
+  - [ ] 判断是否为架构级改进（→ Epic）
+  - [ ] 判断是否为用户价值增量（→ Feature）
+  - [ ] 判断是否为工程债务（→ Chore）
+  - [ ] 判断是否为缺陷修复（→ Fix）
+  - [ ] 评估是否需要前置架构设计
+
+**决策分支**:
+
+| 条件 | 类型 | 下一步 |
+|------|------|--------|
+| 架构愿景级改进，需要分解为多个 Feature | Epic | → Design |
+| 用户可交付价值，有明确验收标准 | Feature | → Direct |
+| 工程维护任务，技术债务清理 | Chore | → Direct |
+| 缺陷修复，有明确复现步骤 | Fix | → Direct |
+| 纯参考资料，无直接改进价值 | - | → Archive |
+| 需要架构设计才能估算工作量 | - | → Design |
+
+### 3. Design (设计) - 可选
+
+- **目标**: 对复杂改进进行初步架构设计
+- **适用**: Epic 或大型 Feature
+- **检查点**:
+  - [ ] 分析现有架构继承性
+  - [ ] 确定技术方案方向
+  - [ ] 识别依赖关系和风险点
+  - [ ] 估算工作量和里程碑
+
+**输出物**:
+- 架构决策记录 (ADR) 草稿
+- 子任务分解建议
+- 依赖 Issue 列表
+
+### 4. Create (创建)
+
+- **目标**: 创建符合规范的 Issue
+- **检查点**:
+  - [ ] 运行 `monoco issue create <type> -t "标题"`
+  - [ ] 编写清晰的描述和背景
+  - [ ] 定义可验证的验收标准（至少 2 个 Checkbox）
+  - [ ] 设置依赖关系（如需要）
+  - [ ] 关联相关 Memo（如适用）
+  - [ ] 运行 `monoco issue lint` 验证合规性
+
+**Issue 内容模板**:
+
+```markdown
+## Objective
+清晰描述这个 Issue 的目标和预期结果。
+
+## Acceptance Criteria
+- [ ] 验收标准 1
+- [ ] 验收标准 2
+
+## Technical Tasks
+- [ ] 技术任务 1
+- [ ] 技术任务 2
+
+## Related
+- Parent: EPIC-XXXX (如适用)
+- Related Memo: MEMO-XXXX (如适用)
+```
+
+### 5. Archive (归档) - 可选
+
+- **目标**: 对无直接改进价值的 Memo 进行归档
+- **检查点**:
+  - [ ] 确认 Memo 内容为纯参考资料
+  - [ ] 记录归档原因
+  - [ ] 更新 Memo 状态（如系统支持）
+
+## Issue 类型指南
+
+| 类型 | 用途 | 前缀 | Mindset | 示例 |
+|------|------|------|---------|------|
+| Epic | 宏大目标、愿景容器 | EPIC- | Architect | 重构核心架构 |
+| Feature | 用户价值增量 | FEAT- | Product Owner | 添加导出功能 |
+| Chore | 工程性事务 | CHORE- | Builder | 升级依赖版本 |
+| Fix | 缺陷修复 | FIX- | Debugger | 修复内存泄漏 |
+
+## 相关命令
+
+```bash
+# 查看待处理 Memo
+monoco memo list
+
+# 创建 Issue
+monoco issue create feature -t "标题"
+monoco issue create chore -t "标题"
+monoco issue create fix -t "标题"
+monoco issue create epic -t "标题"
+
+# 验证 Issue 合规性
+monoco issue lint
+```
+
+## 与 flow_engineer 的关系
+
+此工作流与 `flow_engineer` 互补：
+- `issue-create-workflow`: 关注 Issue 创建阶段，将想法转化为可执行任务
+- `flow_engineer`: 关注代码实现阶段，执行 Investigate → Code → Test → Report → Submit
+
+## Copilot 模式提示
+
+作为 AI Copilot，你应该：
+1. **主动提问**: 当 Memo 内容不清晰时，询问人类开发者意图
+2. **提供选项**: 给出多个分类建议，说明理由
+3. **协助起草**: 帮助编写 Issue 描述和验收标准
+4. **提醒合规**: 确保创建的 Issue 符合项目规范

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

@@ -0,0 +1,224 @@
+---
+name: issue-develop-workflow
+description: 执行 Issue 开发、测试、提交和评审的完整工作流 (Copilot 模式)
+type: flow
+domain: issue
+version: 1.0.0
+---
+
+# Issue Develop Workflow
+
+执行 Issue 开发、测试、提交、评审和合并的完整标准化工作流。
+
+**适用场景**: Copilot 模式（人类主导，AI 辅助）
+**目标用户**: 负责实现功能或修复缺陷的开发者
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Setup: 开始开发
+    
+    Setup --> Develop: 环境就绪
+    Setup --> Setup: 依赖未满足<br/>(等待解决)
+    
+    Develop --> Test: 编码完成
+    Develop --> Develop: 需要迭代<br/>(继续开发)
+    
+    Test --> Submit: 测试通过
+    Test --> Develop: 测试失败<br/>(修复代码)
+    
+    state "Review Loop" as ReviewLoop {
+        Submit --> Review: 提交评审
+        Review --> Fix: 需要修改
+        Fix --> Submit: 重新提交
+    }
+    
+    Review --> Merge: 评审通过
+    
+    Merge --> [*]: 合并完成
+```
+
+## 执行步骤
+
+### 1. Setup (准备)
+
+- **目标**: 准备开发环境，确保可以开始编码
+- **检查点**:
+  - [ ] 运行 `monoco issue start <ID> --branch` 创建功能分支
+  - [ ] 确认分支已创建并切换
+  - [ ] 验证当前不在 main/master 分支
+  - [ ] 检查依赖 Issue 是否已完成
+  - [ ] 确认 Issue 已细化（有技术任务清单）
+
+**环境检查清单**:
+| 检查项 | 命令/方法 |
+|--------|-----------|
+| 当前分支 | `git branch --show-current` |
+| 分支状态 | `git status` |
+| 依赖 Issue | `monoco issue show <ID>` |
+| 代码规范 | 检查项目 lint 配置 |
+
+### 2. Develop (开发)
+
+- **目标**: 实现功能或修复缺陷
+- **策略**: 迭代开发，小步提交
+- **检查点**:
+  - [ ] 遵循项目代码规范
+  - [ ] 编写/更新单元测试
+  - [ ] 定期提交代码（小步提交）
+  - [ ] 更新文件追踪（`monoco issue sync-files`）
+  - [ ] 保持代码可审查性（单次提交 < 400 行）
+
+**开发原则**:
+| 原则 | 说明 |
+|------|------|
+| 小步提交 | 每次提交一个逻辑单元 |
+| 测试先行 | 优先编写测试用例 |
+| 持续同步 | 及时更新文件追踪 |
+| 保持专注 | 避免无关修改 |
+
+### 3. Test (测试)
+
+- **目标**: 确保代码质量和功能正确性
+- **检查点**:
+  - [ ] 运行单元测试，确保通过
+  - [ ] 运行集成测试（如适用）
+  - [ ] 运行代码规范检查（lint）
+  - [ ] 手动验证功能（如需要）
+  - [ ] 检查测试覆盖率
+
+**测试层次**:
+```
+单元测试 → 集成测试 → 端到端测试 → 手动验证
+   ↑          ↑            ↑            ↑
+ 必须        推荐          按需         按需
+```
+
+### 4. Submit (提交)
+
+- **目标**: 准备代码评审
+- **检查点**:
+  - [ ] 运行 `monoco issue lint` 检查合规性
+  - [ ] 修复所有 Lint 错误
+  - [ ] 更新任务清单状态（标记完成项）
+  - [ ] 编写清晰的提交信息
+  - [ ] 运行 `monoco issue submit <ID>`
+
+**提交信息规范**:
+```
+<type>(<scope>): <subject>
+
+<body>
+
+Refs: <ISSUE-ID>
+```
+
+| 类型 | 用途 |
+|------|------|
+| feat | 新功能 |
+| fix | 缺陷修复 |
+| docs | 文档更新 |
+| style | 代码格式 |
+| refactor | 重构 |
+| test | 测试相关 |
+| chore | 构建/工具 |
+
+### 5. Review (评审)
+
+- **目标**: 代码质量和流程合规检查
+- **检查点**:
+  - [ ] 功能是否正确实现
+  - [ ] 代码是否符合设计规范
+  - [ ] 测试是否充分
+  - [ ] 文档是否同步更新
+  - [ ] 是否遵循项目规范
+
+**评审维度**:
+| 维度 | 检查内容 |
+|------|----------|
+| 正确性 | 功能是否按预期工作 |
+| 设计 | 是否符合架构设计 |
+| 测试 | 测试覆盖是否充分 |
+| 规范 | 是否遵循代码规范 |
+| 文档 | 文档是否同步更新 |
+| 性能 | 是否有明显性能问题 |
+| 安全 | 是否有安全隐患 |
+
+### 6. Merge (合并)
+
+- **目标**: 完成 Issue，合并代码
+- **检查点**:
+  - [ ] 代码已通过评审
+  - [ ] 所有 CI 检查通过
+  - [ ] 代码已合并到主分支
+  - [ ] 运行 `monoco issue close <ID> --solution completed --prune`
+  - [ ] 验证分支已清理
+  - [ ] 更新 Review Comments（记录评审反馈）
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 依赖 Issue 未完成 | 返回 Setup，等待依赖 |
+| 测试失败 | 返回 Develop，修复代码 |
+| Lint 失败 | 修复合规性问题，重新 Submit |
+| 评审需要修改 | 返回 Fix，按反馈修改 |
+| 评审通过 | 进入 Merge，合并并清理 |
+
+## 合规要求
+
+- **禁止**: 在 main/master 分支直接修改代码
+- **必须**: 使用 `monoco issue start --branch` 创建功能分支
+- **必须**: 所有单元测试通过后才能 Submit
+- **必须**: 每个 Issue 至少 2 个 Checkbox
+- **必须**: Review/Done 阶段必须包含 Review Comments
+- **建议**: 小步提交，频繁同步文件追踪
+
+## 相关命令
+
+```bash
+# 启动开发
+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
+```
+
+## 与 flow_engineer 的关系
+
+此工作流与 `flow_engineer` 的关系：
+
+```
+issue-develop-workflow          flow_engineer
+       │                              │
+       ├── Setup ─────────────────────┤
+       ├── Develop ←──────────────────┤ Investigate → Code → Test
+       ├── Test ──────────────────────┤
+       ├── Submit ────────────────────┤ Report → Submit
+       ├── Review ────────────────────┤
+       └── Merge ─────────────────────┤
+```
+
+- `issue-develop-workflow`: 关注 Issue 级别的流程管理
+- `flow_engineer`: 关注代码实现的具体技术流程
+
+在 Develop 阶段，开发者应遵循 `flow_engineer` 的 Investigate → Code → Test → Report → Submit 流程。
+
+## Copilot 模式提示
+
+作为 AI Copilot，你应该：
+1. **协助编码**: 帮助实现功能、修复缺陷
+2. **代码审查**: 在提交前进行预审查，发现潜在问题
+3. **测试协助**: 帮助编写测试用例，确保覆盖
+4. **合规检查**: 提醒开发者遵循项目规范
+5. **文档同步**: 协助更新相关文档