monoco-toolkit 0.3.5__tar.gz → 0.3.9__tar.gz

monoco_toolkit-0.3.9/.agent/skills/monoco_flow_i18n_scan_workflow/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: i18n-scan-workflow
+description: I18n 扫描工作流 (Flow Skill)。定义从扫描缺失翻译到生成翻译任务的标准操作流程，确保多语言文档质量。
+type: flow
+domain: i18n
+version: 1.0.0
+---
+
+# I18n Scan Workflow
+
+I18n 扫描的标准化工作流，确保 "Scan → Identify → Generate Tasks" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Scan: 触发扫描
+    
+    Scan --> Identify: 扫描完成
+    Scan --> Scan: 配置错误<br/>(修复配置)
+    
+    Identify --> GenerateTasks: 发现缺失
+    Identify --> [*]: 无缺失<br/>(完成)
+    
+    GenerateTasks --> [*]: 任务生成完成
+```
+
+## 执行步骤
+
+### 1. Scan (扫描)
+
+- **目标**: 扫描项目中所有文档，识别翻译覆盖情况
+- **输入**: 项目文件、i18n 配置
+- **输出**: 扫描报告
+- **检查点**:
+  - [ ] 检查 `.monoco/config.yaml` 中的 i18n 配置
+  - [ ] 运行 `monoco i18n scan`
+  - [ ] 确认源语言和目标语言设置正确
+  - [ ] 验证排除规则（.gitignore、build 目录等）
+
+### 2. Identify (识别缺失)
+
+- **目标**: 分析扫描结果，识别具体缺失的翻译
+- **策略**: 对比源文件和目标文件
+- **检查点**:
+  - [ ] 列出所有缺失翻译的源文件
+  - [ ] 识别缺失的目标语言
+  - [ ] 评估缺失翻译的影响范围
+  - [ ] 按优先级排序（核心文档优先）
+
+### 3. Generate Tasks (生成任务)
+
+- **目标**: 为缺失的翻译创建追踪任务
+- **策略**: 根据缺失情况创建 Issue 或备忘录
+- **检查点**:
+  - [ ] 为核心文档缺失创建 Feature Issue
+  - [ ] 为次要文档缺失创建 Memo 提醒
+  - [ ] 在 Issue 中标注需要翻译的文件路径
+  - [ ] 设置合理的优先级和截止日期
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 配置错误 | 修复 `.monoco/config.yaml`，重新扫描 |
+| 无缺失翻译 | 流程完成，无需进一步操作 |
+| 大量缺失 | 创建 Epic，拆分为多个 Feature |
+| 关键文档缺失 | 高优先级，立即创建 Issue |
+
+## 合规要求
+
+- **必须**: 扫描前验证 i18n 配置正确
+- **必须**: 所有核心文档必须有对应翻译
+- **建议**: 定期运行扫描（如每周）
+- **建议**: 将翻译任务与功能开发绑定
+
+## 相关命令
+
+```bash
+# 扫描缺失翻译
+monoco i18n scan
+
+# 创建翻译任务
+monoco issue create feature -t "翻译 {filename} 到 {lang}"
+
+# 添加备忘录
+monoco memo add "需要翻译: {filepath}"
+```
+
+## 输出示例
+
+扫描完成后，应生成如下报告：
+
+```
+I18n Scan Report
+================
+Source Language: en
+Target Languages: zh, ja
+
+Missing Translations:
+- docs/guide.md → zh/guide.md [MISSING]
+- docs/api.md → ja/api.md [MISSING]
+
+Coverage: 85%
+```

monoco_toolkit-0.3.9/.agent/skills/monoco_flow_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_toolkit-0.3.9/.agent/skills/monoco_flow_note_processing_workflow/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: note-processing-workflow
+description: Memo 笔记处理工作流 (Flow Skill)。定义从捕获 fleeting notes 到组织归档的标准操作流程，确保想法有效管理。
+type: flow
+domain: memo
+version: 1.0.0
+---
+
+# Note Processing Workflow
+
+Memo 笔记处理的标准化工作流，确保 "Capture → Process → Organize → Archive/Convert" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Capture: 想法闪现
+    
+    Capture --> Process: 定期整理
+    Capture --> Capture: 继续记录
+    
+    Process --> Organize: 分类完成
+    Process --> Archive: 无价值<br/>(直接归档)
+    
+    Organize --> Convert: 可执行
+    Organize --> Organize: 需补充<br/>(完善信息)
+    Organize --> Archive: 纯参考<br/>(归档保存)
+    
+    Convert --> [*]: 转为 Issue
+    
+    Archive --> [*]: 归档完成
+```
+
+## 执行步骤
+
+### 1. Capture (捕获)
+
+- **目标**: 快速记录 fleeting ideas，不中断当前工作
+- **输入**: 想法、灵感、代码片段、链接
+- **输出**: Memo 记录
+- **检查点**:
+  - [ ] 使用 `monoco memo add "内容"`
+  - [ ] 保持简洁，无需详细描述
+  - [ ] 添加上下文（`-c file:line` 如适用）
+  - [ ] 不中断当前任务流
+
+### 2. Process (处理)
+
+- **目标**: 定期回顾和分类 Memo
+- **策略**: 定期整理（每日/每周）
+- **检查点**:
+  - [ ] 运行 `monoco memo list` 查看所有 Memo
+  - [ ] 评估每个 Memo 的价值
+  - [ ] 分类：可执行 / 纯参考 / 无价值
+  - [ ] 补充缺失信息
+
+### 3. Organize (组织)
+
+- **目标**: 对有价值的 Memo 进行结构化整理
+- **策略**: 根据类型选择处理方式
+- **检查点**:
+  - [ ] 为相关 Memo 添加标签或分类
+  - [ ] 合并相似的 Memo
+  - [ ] 完善模糊的记录
+  - [ ] 设置优先级（如适用）
+
+### 4. Archive/Convert (归档或转化)
+
+- **目标**: 处理完毕的 Memo 归档或转化为 Issue
+- **检查点**:
+  - [ ] **Convert**: 可执行的想法转为 Issue
+    - 使用 `monoco issue create feature/chore/fix -t "标题"`
+    - 在 Issue 中引用原始 Memo
+  - [ ] **Archive**: 纯参考内容归档保存
+    - 移动到知识库或文档
+    - 从 Memo 列表中移除
+  - [ ] **Delete**: 无价值的 Memo 直接删除
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 想法可执行 | Convert，创建 Issue |
+| 纯参考资料 | Archive，保存到知识库 |
+| 无价值/过时 | Delete，直接删除 |
+| 信息不完整 | 返回 Organize，补充信息 |
+
+## 合规要求
+
+- **必须**: Memo 是临时的，不应无限堆积
+- **必须**: 可执行的想法必须转为 Issue 追踪
+- **建议**: 定期处理（建议每周）
+- **建议**: 保持 Memo 简洁，避免长篇大论
+
+## 相关命令
+
+```bash
+# 添加 Memo
+monoco memo add "考虑使用 Redis 缓存用户会话"
+
+# 带上下文的 Memo
+monoco memo add "递归可能导致栈溢出" -c "src/utils.py:42"
+
+# 查看所有 Memo
+monoco memo list
+
+# 编辑 Memo
+monoco memo open
+
+# 创建 Issue（转化 Memo）
+monoco issue create feature -t "实现 Redis 缓存"
+```
+
+## 使用场景
+
+| 场景 | 使用 Memo | 后续处理 |
+|------|-----------|----------|
+| 代码审查时的改进建议 | `memo add "重构建议: ..."` | Process → Convert to Issue |
+| 会议中的临时想法 | `memo add "想法: ..."` | Process → Organize → Convert |
+| 有用的代码片段 | `memo add "Snippet: ..."` | Process → Archive to 知识库 |
+| 技术文章链接 | `memo add "Read: https://..."` | Process → Archive |
+| Bug 线索 | `memo add "可能的 Bug: ..."` | Process → Convert to Fix Issue |
+
+## 与 Issue 的区别
+
+| 维度 | Memo | Issue |
+|------|------|-------|
+| 目的 | 记录想法 | 追踪任务 |
+| 生命周期 | 临时，需定期清理 | 正式，完整生命周期 |
+| 完成标准 | 归档或转化 | 验收标准通过 |
+| 复杂度 | 简单，一句话 | 详细，有 AC 和 Tasks |
+| 追踪 | 无 | 完整追踪 |
+
+## 最佳实践
+
+1. **及时记录**: 想法闪现时立即记录，避免遗忘
+2. **定期整理**: 每周至少处理一次 Memo 列表
+3. **快速转化**: 有价值的想法尽快转为 Issue
+4. **果断删除**: 过时或无价值的 Memo 果断删除
+5. **保持简洁**: Memo 是速记，不需要详细描述

monoco_toolkit-0.3.9/.agent/skills/monoco_flow_research_workflow/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: research-workflow
+description: Spike 研究工作流 (Flow Skill)。定义从添加外部仓库到知识提取和归档的标准操作流程，确保外部知识有效管理。
+type: flow
+domain: spike
+version: 1.0.0
+---
+
+# Research Workflow
+
+Spike 研究的标准化工作流，确保 "Add → Sync → Analyze → Extract → Archive" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Add: 发现参考仓库
+    
+    Add --> Sync: 添加配置
+    Add --> Add: URL 无效<br/>(重新输入)
+    
+    Sync --> Analyze: 同步完成
+    Sync --> Sync: 同步失败<br/>(网络/权限)
+    
+    Analyze --> Extract: 分析完成
+    Analyze --> Analyze: 内容不符<br/>(重新评估)
+    
+    Extract --> Archive: 知识提取完成
+    
+    Archive --> [*]: 归档完成
+```
+
+## 执行步骤
+
+### 1. Add (添加仓库)
+
+- **目标**: 将外部仓库添加为参考
+- **输入**: 仓库 URL、参考目的
+- **输出**: 配置更新
+- **检查点**:
+  - [ ] 验证仓库 URL 可访问
+  - [ ] 确认仓库与当前项目相关
+  - [ ] 运行 `monoco spike add <url>`
+  - [ ] 检查 `.monoco/config.yaml` 已更新
+
+### 2. Sync (同步)
+
+- **目标**: 下载或更新参考仓库内容
+- **检查点**:
+  - [ ] 运行 `monoco spike sync`
+  - [ ] 验证仓库克隆到 `.references/<name>/`
+  - [ ] 检查同步日志，确认无错误
+  - [ ] 验证文件权限正确（只读）
+
+### 3. Analyze (分析)
+
+- **目标**: 研究参考仓库的结构和内容
+- **策略**: 系统性浏览和标记
+- **检查点**:
+  - [ ] 浏览仓库整体结构
+  - [ ] 识别与当前项目相关的模块
+  - [ ] 标记有价值的代码模式
+  - [ ] 记录架构设计亮点
+
+### 4. Extract (提取知识)
+
+- **目标**: 从参考仓库提取可用知识
+- **策略**: 文档化有价值的发现
+- **检查点**:
+  - [ ] 提取关键代码片段（不修改原文件）
+  - [ ] 记录设计模式和最佳实践
+  - [ ] 创建学习笔记（使用 Memo 或 Issue）
+  - [ ] 标注知识来源（仓库 URL + Commit）
+
+### 5. Archive (归档)
+
+- **目标**: 整理和归档研究成果
+- **检查点**:
+  - [ ] 更新项目文档，引用参考仓库
+  - [ ] 创建知识索引（如需要）
+  - [ ] 运行 `monoco spike list` 验证状态
+  - [ ] 定期清理不再需要的参考
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| URL 无效 | 返回 Add，检查 URL 格式 |
+| 同步失败 | 检查网络、权限，重试或跳过 |
+| 内容不相关 | 从配置中移除，重新选择 |
+| 发现重要模式 | 创建 Issue，计划引入项目 |
+
+## 合规要求
+
+- **禁止**: 编辑 `.references/` 中的任何文件
+- **必须**: 所有外部知识必须标注来源
+- **必须**: 定期同步以获取更新
+- **建议**: 只添加高质量、相关的仓库
+
+## 相关命令
+
+```bash
+# 添加参考仓库
+monoco spike add <url>
+
+# 同步所有仓库
+monoco spike sync
+
+# 列出已配置的仓库
+monoco spike list
+
+# 记录研究发现
+monoco memo add "发现: {insight}" -c "spike:{repo_name}"
+```
+
+## 最佳实践
+
+1. **精选选择**: 只添加与项目高度相关的仓库
+2. **只读访问**: 将 `.references/` 视为外部知识库，永不修改
+3. **定期同步**: 每月运行 `monoco spike sync` 获取更新
+4. **知识转化**: 将学到的模式转化为项目的实际改进

{monoco_toolkit-0.3.5/.claude → monoco_toolkit-0.3.9/.agent}/skills/monoco_issue/SKILL.md

@@ -67,6 +67,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 +180,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 命名约定（如加分级后缀）来表达层级关系。

monoco_toolkit-0.3.9/.agent/skills/monoco_memo/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: monoco-memo
+description: 轻量级备忘录系统，用于快速记录想法、灵感和临时笔记。与正式的 Issue 系统区分开来。
+---
+
+# Monoco Memo (备忘录)
+
+使用此技能快速捕捉 fleeting notes（ fleeting 想法），无需创建正式的 Issue。
+
+## 何时使用 Memo vs Issue
+
+| 场景 | 使用 | 原因 |
+|------|------|------|
+| 临时想法、灵感 | **Memo** | 不需要追踪、不需要完成状态 |
+| 代码片段、链接收藏 | **Memo** | 快速记录，后续整理 |
+| 会议速记 | **Memo** | 先记录，再提炼成任务 |
+| 可执行的工作单元 | **Issue** | 需要追踪、验收标准、生命周期 |
+| Bug 修复 | **Issue** | 需要记录复现步骤、验证结果 |
+| 功能开发 | **Issue** | 需要设计、分解、交付 |
+
+> **核心原则**: Memos 记录**想法**；Issues 处理**可执行任务**。
+
+## 命令
+
+### 添加备忘录
+
+```bash
+monoco memo add "你的备忘录内容"
+```
+
+可选参数:
+- `-c, --context`: 添加上下文引用（如 `file:line`）
+
+示例:
+```bash
+# 简单记录
+monoco memo add "考虑使用 Redis 缓存用户会话"
+
+# 带上下文的记录
+monoco memo add "这里的递归可能导致栈溢出" -c "src/utils.py:42"
+```
+
+### 查看备忘录列表
+
+```bash
+monoco memo list
+```
+
+显示所有未归档的备忘录。
+
+### 打开备忘录文件
+
+```bash
+monoco memo open
+```
+
+在默认编辑器中打开备忘录文件，用于整理或批量编辑。
+
+## 工作流程
+
+```
+想法闪现 → monoco memo add "..." → 定期整理 → 提炼成 Issue 或归档
+```
+
+1. **捕捉**: 有想法时立即使用 `monoco memo add` 记录
+2. **整理**: 定期（如每日/每周）运行 `monoco memo list` 回顾
+3. **转化**: 将有价值的备忘录转化为正式的 Issue
+4. **归档**: 处理完毕后从备忘录中移除
+
+## 最佳实践
+
+1. **保持简洁**: Memo 是速记，不需要详细描述
+2. **及时转化**: 有价值的想法应尽快转为 Issue，避免遗忘
+3. **定期清理**: Memos 是临时的，不要让它们无限堆积
+4. **使用上下文**: 记录代码相关想法时，使用 `-c` 参数标注位置